BookStack MCP Server

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation5/5
Every tool has a clearly distinct purpose with no ambiguity, as each combines a specific action (create, get, list, update, delete, export) with a specific resource type (book, chapter, page, role, shelf, user, attachment, image). The search_all tool is distinct in covering multiple resources. No tools appear to do the same thing.
Naming Consistency5/5
All tools follow a consistent verb_noun pattern throughout, using snake_case with clear action verbs (create, get, list, update, delete, export) paired with resource nouns. There are no deviations or mixed conventions, making the naming highly predictable and readable.
Tool Count2/5
With 41 tools, the count is excessive for the server's purpose of managing a documentation/wiki system. This feels heavy and could overwhelm agents, as many tools are repetitive across resources (e.g., create/delete/update for each resource type). A more streamlined set would improve usability.
Completeness5/5
The tool surface provides complete CRUD/lifecycle coverage for the domain, including create, get, list, update, delete, and export operations for all core resources (books, chapters, pages, roles, shelves, users, attachments, images), plus search functionality. There are no obvious gaps or dead ends for agent workflows.
Average 3/5 across 41 of 41 tools scored. Lowest: 2.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
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.
Add a glama.json file to provide metadata about your server.
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 are provided, so the description carries full burden for behavioral disclosure. 'Update image details' implies a mutation operation but doesn't specify permissions required, whether changes are reversible, rate limits, or what happens to unspecified fields. For a mutation tool with zero annotation coverage, this minimal description fails to provide adequate 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?
The description is extremely concise with a single three-word phrase. While under-specified, it's not verbose or poorly structured—every word earns its place by identifying the action and resource. No redundant or filler content is present.
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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'details' can be updated beyond the schema's name parameter, doesn't describe the return value or error conditions, and lacks context about the update operation's scope or effects. Given the complexity implied by sibling tools, this is inadequate.
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 both parameters (id and name) documented in the schema. The description adds no parameter-specific information beyond what the schema provides—it doesn't explain what 'image details' includes or constraints on the name field. Baseline score of 3 is appropriate since the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update image details' is a tautology that restates the tool name 'update_image' without adding meaningful specificity. It mentions the resource ('image') but lacks a clear verb beyond 'update' and doesn't distinguish this tool from sibling update tools like update_book or update_user. No evidence of what 'details' encompasses or how this differs from other update operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing image ID), exclusions, or comparisons to siblings like delete_image or get_image. With multiple update tools in the sibling list, the absence of any contextual usage information is a significant gap.
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 of behavioral disclosure. 'Update an existing book' implies a mutation operation, but it doesn't specify permissions required, whether changes are reversible, rate limits, or what happens to fields not included in the update. For a mutation tool with zero annotation coverage, this is a significant gap in 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 extremely concise at just three words, which is efficient and front-loaded. However, it's arguably too brief given the tool's complexity (6 parameters, mutation operation), leaving important context unaddressed. It earns a 4 for zero waste but loses a point for under-specification.
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 this is a mutation tool with 6 parameters, no annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects (permissions, side effects), usage context, or return values. The agent lacks sufficient information to use this tool safely and effectively beyond basic parameter mapping.
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 input schema already documents all parameters thoroughly. The description adds no additional meaning about parameters beyond what's in the schema (e.g., it doesn't explain relationships between fields like description vs. description_html). Baseline score of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing book' clearly states the action (update) and resource (book), but it's vague about what specifically gets updated. It doesn't distinguish this tool from other update_* siblings like update_chapter or update_page, which all follow the same pattern of updating a resource.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing book ID), when not to use it, or how it differs from sibling tools like create_book or get_book. The agent must infer usage from the tool name alone.
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?
With no annotations provided, the description carries full burden but only states it's a creation operation. It doesn't disclose behavioral traits like authentication requirements, rate limits, whether the operation is idempotent, what happens on duplicate names, or what the response contains. For a mutation tool with zero annotation coverage, this is a significant 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?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a simple creation tool and front-loads the core action.
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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what a 'book' represents in this system, what happens after creation, or any side effects. The agent must rely entirely on the input schema for operational details.
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 schema fully documents all 5 parameters. The description adds no parameter-specific information beyond implying a 'book' is created. Baseline 3 is appropriate when the schema does all the parameter documentation work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the basic action ('Create a new book') but is vague about what constitutes a 'book' in this system and doesn't differentiate from sibling tools like 'create_chapter' or 'create_page'. It provides the verb+resource but lacks specificity about the resource's nature or 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 is provided on when to use this tool versus alternatives like 'update_book' or 'list_books'. The description doesn't mention prerequisites, constraints, or typical use cases, leaving the agent to infer usage from the tool name alone.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action ('Get a listing') without mentioning pagination behavior, rate limits, authentication needs, or what the return format looks like (e.g., list structure, error handling). This leaves significant gaps for a tool that likely returns multiple items.
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 a single sentence ('Get a listing of attachments'), which is front-loaded and wastes no words. Every part of the sentence directly contributes to stating the tool's purpose, making it efficient in structure.
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 (listing operation with pagination/sorting) and lack of annotations or output schema, the description is incomplete. It doesn't explain the return format, pagination behavior, or error conditions, which are critical for an agent to use this tool effectively in a real-world context.
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, with clear documentation for 'page', 'count', and 'sort' parameters. The description adds no additional meaning beyond the schema, such as default values, valid sort options, or parameter interactions. Baseline score of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a listing of attachments' states a clear verb ('Get') and resource ('attachments'), but it's vague about scope and doesn't differentiate from sibling tools like 'list_books', 'list_chapters', or 'get_attachment'. It lacks specificity about what kind of attachments or what context they belong to.
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. It doesn't mention when to choose 'list_attachments' over 'get_attachment' for a single attachment, or over 'search_all' for broader queries, nor does it specify any prerequisites or exclusions for usage.
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 of behavioral disclosure. 'Update an existing chapter' implies a mutation operation, but the description doesn't specify what happens during updates (e.g., whether fields are optional, if changes are reversible, permission requirements, or error conditions). For a mutation tool with zero annotation coverage, this leaves critical behavioral traits undocumented.
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 with zero wasted words. It's front-loaded with the core action and resource, making it easy to parse. Every word earns its place, and there's no redundancy or fluff.
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 complexity (a mutation tool with 7 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like side effects, error handling, or return values, leaving significant gaps for the agent. While the schema covers parameters well, the overall context for safe and effective use is insufficient.
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%, meaning all 7 parameters are documented in the input schema. The description adds no parameter-specific information beyond what's in the schema (e.g., it doesn't explain relationships between parameters like description vs. description_html). With high schema coverage, the baseline score of 3 is appropriate—the description doesn't compensate but doesn't need to since the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing chapter' clearly states the action (update) and resource (chapter), which is better than a tautology. However, it doesn't distinguish this tool from sibling update tools like update_book, update_page, or update_user, all of which follow the same 'Update an existing X' pattern. The purpose is clear but lacks differentiation.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing chapter ID), when not to use it (e.g., for creating vs. updating), or refer to related tools like create_chapter or get_chapter. Without any usage context, the agent must infer everything from the tool name and schema.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Update an existing page' implies a mutation operation but doesn't disclose permission requirements, whether changes are reversible, rate limits, or what happens to unspecified fields. It mentions no side effects or response format, leaving significant behavioral 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 extremely concise - a single three-word phrase that's front-loaded with the essential action. There's zero wasted verbiage, though this conciseness comes at the cost of completeness.
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?
For a mutation tool with 8 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what 'update' entails (partial vs full updates), doesn't mention the required ID parameter, and provides no context about the update operation's behavior or results.
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 all parameters are documented in the schema. The description adds no additional parameter information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing page' clearly states the action (update) and resource (page), but it's generic and doesn't distinguish this from other update tools like update_book or update_chapter. It specifies the target is 'existing' which helps differentiate from create_page, but lacks specificity about what aspects can be updated.
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 about when to use this tool versus alternatives. The description doesn't mention prerequisites (like needing the page ID), when not to use it, or how it differs from other update tools. The agent must infer usage from the parameter schema alone.
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?
With no annotations, the description carries full burden but only states 'update' without disclosing behavioral traits like whether changes are reversible, permission requirements, or side effects (e.g., permissions array replaces existing). It lacks critical details for a mutation tool, making it insufficient for safe use.
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 with zero waste. It's front-loaded and appropriately sized for the tool's complexity, earning its place without unnecessary elaboration.
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?
For a mutation tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects, return values, or error conditions, leaving significant gaps that could hinder an AI agent's ability to use the tool correctly.
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 schema fully documents all 5 parameters. The description adds no meaning beyond the schema, as it doesn't explain parameter interactions or usage examples. Baseline 3 is appropriate since the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing role' clearly states the verb (update) and resource (role), but it's vague about what aspects can be updated and doesn't distinguish from sibling tools like update_user or update_book. It provides basic purpose but lacks specificity 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 is provided on when to use this tool versus alternatives like create_role or delete_role, nor does it mention prerequisites (e.g., needing an existing role ID). The description assumes context without explicit instructions, leaving gaps for an AI agent.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Update an existing shelf' implies a mutation operation but doesn't specify permissions needed, whether changes are reversible, rate limits, or what happens to unspecified fields (partial vs. full updates). The description lacks critical behavioral context for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a basic update operation and front-loads the essential information (verb + resource).
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?
For a mutation tool with 6 parameters, no annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects (permissions, side effects), usage context, or return values. The schema covers parameters well, but the description fails to compensate for missing annotation and output information.
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 all parameters are documented in the schema itself. The description adds no additional meaning about parameters beyond what's in the schema (e.g., it doesn't clarify that 'books' replaces existing books or that 'id' is required). Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing shelf' clearly states the action (update) and resource (shelf), but it's vague about what specifically gets updated. It doesn't distinguish this tool from other update_* siblings like update_book or update_user, which all follow the same pattern.
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. The description doesn't mention prerequisites (e.g., needing an existing shelf ID), when not to use it, or how it differs from create_shelf or other update operations in the sibling list.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a creation operation but doesn't mention permissions required, whether it's idempotent, what happens on failure, or the format of the response. For a mutation tool with zero annotation coverage, this leaves significant behavioral 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, clear sentence with no wasted words. It's appropriately sized and front-loaded with the essential information, making it highly efficient.
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?
For a creation tool with 7 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the tool returns, error conditions, or behavioral constraints. Given the complexity and lack of structured data, it should provide more context to be complete.
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%, so all parameters are documented in the schema itself. The description adds no additional parameter semantics beyond implying a 'book' context, which is already covered by the 'book_id' parameter. This meets the baseline for high schema coverage.
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 ('Create') and resource ('new chapter in a book'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'create_page' or 'create_book' beyond specifying the resource type, which is a minor gap.
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 provides no guidance on when to use this tool versus alternatives like 'create_page' or 'create_book', nor does it mention prerequisites such as needing an existing book. It simply states what it does without contextual usage information.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates something but doesn't mention permissions needed, whether the operation is idempotent, what happens on failure, or what the return value might be. For a creation tool with zero annotation coverage, this leaves significant behavioral 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, efficient sentence that states the core purpose without any fluff. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.
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?
For a creation tool with 7 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what happens after creation, error conditions, or how it differs from similar tools. The agent would need to guess about behavioral aspects and output format.
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 schema already documents all 7 parameters thoroughly. The description adds no additional parameter information beyond implying the hierarchical relationship ('in a book or chapter'), which aligns with the schema's book_id/chapter_id parameters. This meets the baseline for high schema coverage.
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 ('Create') and resource ('new page in a book or chapter'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'create_chapter' or 'create_book' beyond the resource type, which prevents a perfect score.
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 provides no guidance on when to use this tool versus alternatives like 'create_chapter' or 'update_page'. There's no mention of prerequisites (e.g., needing a book or chapter first) or exclusions, leaving the agent to infer usage from context alone.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Create a new role' implies a write operation but lacks details on permissions required, whether the role is immediately active, potential side effects, or error conditions. This is inadequate for a mutation tool with zero annotation coverage.
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 with zero wasted words. It is front-loaded and appropriately sized for its purpose, making it easy to parse quickly.
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 complexity of a mutation tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral traits, usage context, and return values, leaving significant gaps for an AI agent to understand how to invoke it correctly.
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 schema fully documents all parameters. The description adds no additional meaning beyond the schema, such as examples or constraints. Baseline 3 is appropriate when the schema does the heavy lifting, but no extra value is provided.
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 'Create a new role' clearly states the verb ('Create') and resource ('role'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'create_user' or 'create_book' beyond specifying the resource type, which is why it doesn't reach the highest score.
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 provides no guidance on when to use this tool versus alternatives. There are no mentions of prerequisites, when-not-to-use scenarios, or comparisons with sibling tools like 'update_role' or 'list_roles', leaving the agent without context for selection.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Create a new shelf' implies a write operation but doesn't address permissions, side effects, error conditions, or what happens on success. For a creation tool with zero annotation coverage, this is insufficient 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?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a simple creation operation and front-loads the essential information.
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?
For a creation tool with 5 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what gets returned, error handling, or system behavior beyond the basic creation action. The schema covers parameters well, but the overall context is incomplete.
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 schema fully documents all 5 parameters. The description adds no parameter information beyond what's in the schema, maintaining the baseline score of 3 where the schema does the heavy lifting.
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 verb ('Create') and resource ('new shelf'), making the purpose immediately understandable. It doesn't differentiate from sibling tools like 'create_book' or 'create_user', but it's unambiguous about what it creates.
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 provides no guidance on when to use this tool versus alternatives like 'update_shelf' or 'list_shelves'. It doesn't mention prerequisites, constraints, or typical use cases, leaving the agent to infer usage from context alone.
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?
With no annotations provided, the description carries full burden for behavioral disclosure but only states the basic action. It doesn't mention authentication requirements, whether the operation is idempotent, what happens on duplicate email, rate limits, or what the response contains. 'Create' implies mutation but lacks critical 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?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a straightforward creation tool and gets directly to the point without unnecessary elaboration.
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?
For a mutation tool with 7 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what happens after creation, error conditions, permissions needed, or how this fits into the broader user management system. The agent lacks critical context for proper tool invocation.
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 parameters are fully documented in the schema. The description adds no additional parameter information beyond what's in the schema, but doesn't need to since the schema is comprehensive. Baseline 3 is appropriate when schema does the heavy lifting.
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 ('Create') and resource ('new user account'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'create_role' or 'create_book' beyond the resource type, and doesn't specify what constitutes a 'user account' in this system context.
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 provides no guidance on when to use this tool versus alternatives like 'update_user' or 'get_user', nor does it mention prerequisites, permissions required, or typical workflows. The agent must infer usage from the tool name alone.
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 of behavioral disclosure. 'Delete an attachment' implies a destructive mutation, but it doesn't specify whether deletion is permanent, reversible, requires specific permissions, or has side effects (e.g., affecting linked resources). This leaves critical behavioral traits undocumented for a destructive 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 is extremely concise at three words, with zero wasted language. It's front-loaded with the core action and resource, making it easy to parse. For a simple delete operation, this brevity is appropriate rather than under-specified.
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 destructive nature, lack of annotations, and no output schema, the description is incomplete. It doesn't address behavioral risks, success/failure responses, or contextual nuances (e.g., what an 'attachment' is in this system). For a mutation tool with zero structured safety hints, more descriptive context is needed.
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 100% description coverage (the 'id' parameter is documented as 'Attachment ID'), so the baseline is 3. The description doesn't add any parameter details beyond what the schema provides, but with only one required parameter and full schema coverage, this is minimally adequate. A score of 4 reflects that the tool is simple enough that extensive parameter explanation isn't necessary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete an attachment' clearly states the verb (delete) and resource (attachment), making the basic purpose understandable. However, it doesn't differentiate from sibling tools like delete_book, delete_chapter, or delete_image, which all follow the same 'delete [resource]' pattern without clarifying what distinguishes an attachment from other deletable resources.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing the attachment ID), exclusions, or relationships with sibling tools like get_attachment or list_attachments. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 of behavioral disclosure. It states 'Delete' which implies a destructive mutation, but doesn't clarify if this is permanent, reversible, requires specific permissions, or has side effects (e.g., affecting related data). This is a significant gap for a mutation tool with zero annotation coverage.
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, clear sentence with no wasted words, making it highly concise and front-loaded. It directly communicates the core action without unnecessary elaboration, earning full marks for efficiency.
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 destructive nature (implied by 'Delete'), no annotations, and no output schema, the description is incomplete. It should address behavioral aspects like permanence, permissions, or error handling to adequately guide the agent, but it lacks such details, making it insufficient for safe and effective use.
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%, with the single parameter 'id' documented as 'Image ID' in the schema. The description doesn't add any meaning beyond this, such as format examples or constraints, so it meets the baseline of 3 where the schema handles parameter documentation adequately.
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 ('Delete') and resource ('an image from the gallery'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'delete_attachment', 'delete_book', etc., which follow the same pattern but target different resources, so it lacks sibling distinction.
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 provides no guidance on when to use this tool versus alternatives. For example, it doesn't mention if this is for permanent deletion, if there are prerequisites like having the image ID, or how it differs from other delete operations in the sibling list, leaving the agent without contextual usage cues.
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 mentions 'various formats' but doesn't specify what the export does (e.g., generates a file, returns content, requires permissions, has rate limits, or side effects). This leaves critical behavioral traits undocumented for a mutation-like 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 is a single, efficient sentence with no wasted words. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration.
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 annotations and no output schema, the description is incomplete for a tool that likely performs a mutation (exporting data). It lacks details on what the export produces, any side effects, error conditions, or how it differs from similar export tools, leaving significant gaps in 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 description coverage is 100%, so the schema fully documents both parameters (id and format with enum). The description adds no additional meaning beyond implying format options with 'various formats', which the schema already covers explicitly. This meets the baseline for high schema coverage.
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 ('Export') and resource ('a book'), specifying the verb+resource combination. However, it doesn't differentiate from sibling tools like 'export_chapter' or 'export_page' that perform similar export operations on different resources, which prevents a perfect score.
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 provides no guidance on when to use this tool versus alternatives like 'export_chapter' or 'export_page', nor does it mention any prerequisites or contextual constraints. It simply states what the tool does without usage instructions.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action 'export' but doesn't describe what this entails—whether it's a read-only operation, if it generates downloadable files, requires permissions, has side effects, or what the output looks like. This leaves significant behavioral gaps for a mutation-like 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 is a single, efficient sentence that directly states the tool's function without unnecessary words. It's appropriately sized for a simple tool and front-loads the core purpose effectively.
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?
For an export tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'export' means operationally, what the result is (e.g., file generation, data return), or any behavioral traits. Given the complexity of an export operation and lack of structured context, more completeness is needed.
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 schema fully documents both parameters (id and format with enum). The description adds no additional parameter semantics beyond what's in the schema, such as explaining what a 'chapter ID' refers to or providing context about format choices. This meets the baseline for high schema coverage.
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 verb 'export' and resource 'chapter', making the purpose immediately understandable. It distinguishes from siblings like 'export_book' and 'export_page' by specifying the chapter resource, though it doesn't explicitly differentiate when to choose between these export tools.
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 provides no guidance on when to use this tool versus alternatives like 'export_book' or 'export_page'. It doesn't mention prerequisites, constraints, or typical use cases, leaving the agent to infer usage from context alone.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool exports a page but doesn't reveal critical traits: whether it's read-only or destructive, if it requires specific permissions, what the output looks like (e.g., file download or data return), or any rate limits. For a tool with zero annotation coverage, this is a significant gap in 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 a single, efficient sentence that directly states the tool's function. It's front-loaded with the core action and resource, with no wasted words. However, it could be slightly more structured by explicitly mentioning parameters or output, though its brevity is generally effective.
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 (export operation with 2 required parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects (e.g., output format, side effects), usage context, or parameter details beyond what the schema provides. For a tool with this profile, more comprehensive information is needed.
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, with clear docs for 'id' and 'format' (including an enum). The description adds minimal value beyond the schema by implying parameter usage ('Export a page in various formats'), but doesn't explain semantics like what a Page ID represents or format implications. Baseline 3 is appropriate as the schema does the heavy lifting.
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 ('Export') and resource ('a page'), specifying it can be done 'in various formats'. This distinguishes it from other export tools like export_book and export_chapter by focusing on pages. However, it doesn't explicitly differentiate from sibling tools beyond the resource type, which prevents a perfect score.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing page ID), compare it to other export tools (export_book, export_chapter), or indicate scenarios where it's preferred over other operations like get_page. This lack of contextual direction leaves the agent without usage cues.
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 of behavioral disclosure. It states 'Get details' but does not specify what details are returned (e.g., metadata, content, permissions), whether it's a read-only operation, error conditions, or authentication needs. This is a significant gap for a tool with no annotation coverage.
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 ('Get details of a specific attachment') that is front-loaded and wastes no words. It directly conveys the core purpose without unnecessary elaboration, making it highly concise and well-structured.
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 complexity (a retrieval tool with no annotations and no output schema), the description is incomplete. It lacks details on return values (e.g., what 'details' include), error handling, or behavioral traits like rate limits. For a tool with rich sibling context and no structured output, more information is needed to ensure proper agent 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?
The input schema has 100% description coverage, with the 'id' parameter documented as 'Attachment ID'. The description does not add any meaning beyond this, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the schema handles parameter documentation adequately.
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 'Get details of a specific attachment' clearly states the verb ('Get') and resource ('attachment'), making the purpose understandable. However, it does not explicitly differentiate from sibling tools like 'list_attachments' (which likely lists multiple attachments) or 'get_book' (which retrieves a different resource), missing full sibling distinction.
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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing an attachment ID), exclusions, or comparisons to siblings like 'list_attachments' for bulk retrieval or 'get_image' for specific attachment types, leaving usage context unclear.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Get details' but doesn't specify what details are returned, if authentication is required, or any rate limits. This leaves significant gaps for a tool that likely fetches data.
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 with zero waste, clearly front-loaded with the core action. It earns its place by succinctly conveying the tool's purpose.
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 lack of annotations and output schema, the description is incomplete. It doesn't explain what details are returned, error conditions, or behavioral traits, making it inadequate for a tool that likely involves data retrieval without structured output documentation.
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, with the 'id' parameter documented as 'Image ID'. The description adds no additional meaning beyond this, such as format examples or constraints, so it meets the baseline for high schema coverage.
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 verb ('Get details') and resource ('of a specific image'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'list_images' or 'update_image' beyond the basic action, missing explicit scope comparison.
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 such as 'list_images' for multiple images or 'update_image' for modifications. The description implies usage for a single image but lacks explicit context or exclusions.
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 of behavioral disclosure. It states it 'gets details and content,' implying a read-only operation, but does not specify aspects like authentication needs, rate limits, error handling, or return format. This leaves significant gaps for a tool with no annotation support.
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 directly states the tool's function without unnecessary words. It is front-loaded and appropriately sized for its purpose, making it easy to parse quickly.
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 lack of annotations and output schema, the description is incomplete. It does not explain what 'details and content' includes, how results are structured, or any behavioral traits like safety or performance. For a retrieval tool in a context with many siblings, more context is needed to guide effective use.
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, with the 'id' parameter clearly documented as 'Page ID.' The description does not add any extra meaning beyond this, such as format examples or constraints, so it meets the baseline for high schema coverage without compensation.
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 verb ('Get') and resource ('details and content of a specific page'), making the purpose understandable. However, it does not differentiate from sibling tools like 'get_book' or 'get_chapter', which have similar retrieval purposes for different resources, so it lacks sibling distinction.
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 provides no guidance on when to use this tool versus alternatives, such as 'list_pages' for browsing or 'search_all' for broader queries. There is no mention of prerequisites, exclusions, or contextual usage, leaving the agent with minimal direction.
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 this is a read operation ('Get'), but doesn't mention authentication requirements, rate limits, error conditions, or what 'details' include beyond books. For a tool with no annotation coverage, this leaves significant behavioral gaps about how the tool actually works.
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 immediately states the tool's core function. Every word contributes meaning: 'Get' (action), 'details' (scope), 'specific shelf' (target), 'including its books' (key output). There's no wasted text, repetition, or unnecessary elaboration.
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?
For a read operation with no annotations and no output schema, the description is insufficient. It mentions 'details' and 'books' but doesn't explain the return format, whether books are full objects or just references, or what other shelf details are included. The agent lacks critical information about what to expect from this tool's response.
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 the single parameter 'id' fully documented in the schema as 'Shelf ID'. The description doesn't add any parameter information beyond what the schema provides (no format examples, constraints, or relationship to 'books'). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't enhance parameter understanding.
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 tool's purpose with a specific verb ('Get') and resource ('shelf'), and specifies what details are included ('including its books'). It distinguishes this from list_shelves (which would list multiple shelves) but doesn't explicitly differentiate from other get_* tools like get_book or get_user. The purpose is clear but sibling differentiation is incomplete.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (like needing a shelf ID), when not to use it (e.g., for listing shelves), or refer to sibling tools like list_shelves or search_all. The agent must infer usage from the tool name and context alone.
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 of behavioral disclosure. It states the tool retrieves a listing, implying a read-only operation, but doesn't cover critical aspects like pagination behavior (implied by parameters but not explained), rate limits, authentication needs, or what 'visible to the user' entails (e.g., permissions). For a list tool with zero annotation coverage, this leaves significant 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, efficient sentence that front-loads the core purpose ('Get a listing of books') and adds a useful qualifier ('visible to the user'). There is no wasted verbiage or redundancy, making it highly concise and well-structured for quick understanding.
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 (a list operation with pagination/sorting) and lack of annotations and output schema, the description is incomplete. It doesn't explain the return format, pagination behavior, or how 'visible to the user' affects results. For a tool with three parameters and no structured output info, more context is needed to guide effective use.
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, with clear documentation for 'page', 'count', and 'sort'. The description adds no parameter-specific information beyond implying a listing operation. According to scoring rules, with high schema coverage (>80%), the baseline is 3 even without param details in the description, which applies here.
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 tool's purpose with a specific verb ('Get') and resource ('listing of books'), making it immediately understandable. It adds the scope 'visible to the user', which distinguishes it from potentially unfiltered listings. However, it doesn't explicitly differentiate from sibling tools like 'search_all' or 'get_book', which could provide similar book-related data.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'search_all' (which might offer filtering) or 'get_book' (for single books), nor does it specify prerequisites or contexts for use. The agent must infer usage from the tool name and description alone.
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 of behavioral disclosure. It states the tool retrieves a listing but omits critical details like whether it's paginated (implied by parameters but not described), what the output format is, rate limits, authentication needs, or error conditions. For a read operation with zero annotation coverage, 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?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every part of the sentence contributes meaning, earning its place.
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 complexity of a listing tool with pagination and sorting parameters, no annotations, and no output schema, the description is incomplete. It fails to explain the return format, pagination behavior, or how visibility filtering works, leaving significant gaps for an agent to understand the tool's full behavior.
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, with clear parameter descriptions for 'page', 'count', and 'sort'. The description adds no additional semantic context about these parameters, such as default values, valid ranges, or how 'sort' works. Baseline 3 is appropriate since the schema does the heavy lifting, but the description doesn't enhance understanding.
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 ('Get a listing') and resource ('pages'), specifying that it retrieves pages 'visible to the user', which adds useful context about scope. However, it doesn't explicitly differentiate from sibling tools like 'list_books' or 'list_chapters' beyond the resource name, missing an opportunity to clarify what makes listing pages distinct.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_page' (for single pages) or 'search_all' (for broader searches), nor does it specify prerequisites or contexts for usage. This leaves the agent without direction on tool selection.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a read operation ('Get'), but doesn't mention whether it's paginated (though parameters imply it), what the return format is, or any rate limits or permissions needed. This leaves significant gaps for a tool that likely interacts with system data.
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 directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly.
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?
For a tool that lists system roles with no annotations and no output schema, the description is inadequate. It doesn't explain what data is returned, how results are structured, or any behavioral nuances like pagination defaults or error handling. This leaves too much uncertainty for effective use.
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, clearly documenting all three parameters (page, count, sort). The description adds no additional semantic context beyond implying a listing operation, so it meets the baseline of 3 where the schema does the heavy lifting without compensating for any gaps.
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 verb ('Get') and resource ('listing of roles in the system'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from its sibling 'get_role' (which likely retrieves a single role), leaving some ambiguity about when to use one versus the other.
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 provides no guidance on when to use this tool versus alternatives like 'get_role' or 'search_all'. It lacks context about prerequisites, such as whether authentication is required, and doesn't mention any exclusions or specific scenarios where this tool is preferred.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure but only states the basic action. It doesn't mention whether this is a read-only operation, if it requires specific permissions, what the output format looks like, or any rate limits. This leaves significant gaps for a tool that likely returns sensitive user data.
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, clear sentence that efficiently conveys the core purpose without any wasted words. It's front-loaded with the essential information, making it easy for an agent to parse quickly and accurately.
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 lack of annotations and output schema, the description is insufficient for a tool that handles user listings. It doesn't explain what user data is returned, how pagination works in practice, or any behavioral constraints, leaving the agent with incomplete context for safe and effective use.
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, clearly documenting all three parameters (page, count, sort) with their purposes. The description adds no additional parameter information beyond what the schema provides, so it meets the baseline score of 3 for adequate but not enhanced parameter semantics.
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 ('Get a listing') and resource ('users in the system'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_roles' or 'list_shelves', which follow the same pattern for different resources, preventing a perfect score.
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 provides no guidance on when to use this tool versus alternatives like 'get_user' (for single user details) or 'search_all' (for broader queries). It lacks context about prerequisites, such as authentication needs or when pagination is necessary, leaving the agent to infer usage from the tool name alone.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Update an existing user account' implies mutation but doesn't specify what permissions are required, whether changes are reversible, what happens to unspecified fields, or what the response looks like. For a mutation tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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 with zero wasted words. It's appropriately sized for a straightforward update operation and gets directly to the point without unnecessary elaboration.
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?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens during the update, what the response contains, or any constraints beyond what's implied by 'update.' Given the complexity of user account updates (which often involve permissions, validation, and side effects), more context is needed.
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%, with all 7 parameters well-documented in the schema itself. The description adds no parameter-specific information beyond what's already in the schema, so it meets the baseline score of 3 for high schema coverage without adding extra value.
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 verb ('update') and resource ('existing user account'), making the purpose immediately understandable. However, it doesn't differentiate this tool from other update_* siblings like update_book or update_role, which all follow the same pattern of updating different resource types.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (like needing the user ID), when not to use it, or how it differs from create_user or other user management tools. The agent must infer usage from context alone.
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 of behavioral disclosure. It states the tool retrieves details but doesn't cover critical aspects like whether it's a read-only operation (implied by 'Get' but not explicit), error handling (e.g., for invalid IDs), authentication needs, rate limits, or response format. For a retrieval tool with zero annotation coverage, this leaves significant gaps in understanding its 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 a single, efficient sentence: 'Get details of a specific book including its content structure.' It is front-loaded with the core purpose and avoids unnecessary words. Every part of the sentence contributes value by specifying what is retrieved and the scope.
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 tool's low complexity (single parameter, no nested objects) and high schema coverage, the description is minimally adequate. However, with no annotations and no output schema, it lacks details on behavioral traits (e.g., safety, errors) and return values. The description covers the basic purpose but doesn't compensate for the missing structured data, making it incomplete for fully informed 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?
The input schema has 100% description coverage, with the 'id' parameter documented as 'Book ID.' The description adds no additional parameter semantics beyond what the schema provides (e.g., it doesn't explain ID format, sourcing, or constraints). According to the rules, with high schema coverage (>80%), the baseline score is 3 even without param info in the description.
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 tool's purpose: 'Get details of a specific book including its content structure.' It specifies the verb ('Get'), resource ('book'), and scope ('details' and 'content structure'), distinguishing it from siblings like list_books (which lists multiple books) or get_chapter (which retrieves chapter-specific details). However, it doesn't explicitly differentiate from other get_* tools (e.g., get_chapter) beyond the resource type.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a book ID), contrast with list_books for browsing, or specify use cases like retrieving full book metadata. Without such context, the agent must infer usage from the tool name and schema alone.
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. It implies a read-only operation by using 'Get', but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or whether it's idempotent. For a tool with no annotation coverage, this is a significant gap in 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 a single, efficient sentence that front-loads the core purpose without unnecessary details. It's appropriately sized for a simple retrieval tool, with zero 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?
Given the tool's low complexity (single parameter, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks completeness in usage guidance and behavioral context, making it functional but with clear gaps for an AI agent.
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, with the 'id' parameter clearly documented. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints. Baseline 3 is appropriate as the schema does the heavy lifting.
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 verb 'Get' and resource 'details of a specific chapter including its pages', which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_book' or 'get_page', which also retrieve details of related resources, so it misses full sibling distinction.
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 provides no guidance on when to use this tool versus alternatives such as 'list_chapters' for multiple chapters or 'get_book' for broader book details. It lacks explicit context, prerequisites, or exclusions, leaving usage unclear in the tool ecosystem.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it 'Get details' but doesn't clarify if this is a read-only operation, what permissions are required, error handling, or response format. This is inadequate for a tool with potential security implications.
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 front-loads the core purpose without any wasted words. It is appropriately sized for a simple retrieval tool.
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 tool's low complexity (single parameter, no output schema, no annotations), the description is minimally adequate but lacks details on usage context, behavioral traits, or output expectations. It doesn't fully compensate for the absence of annotations or output schema.
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%, with the parameter 'id' clearly documented as 'Role ID'. The description adds no additional meaning beyond this, such as format examples or constraints, so it meets the baseline for high schema coverage.
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 verb 'Get' and the resource 'details of a specific role including permissions', which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'list_roles' or 'create_role', which would require a 5.
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 provides no guidance on when to use this tool versus alternatives like 'list_roles' for listing all roles or 'create_role' for creating a new role. It lacks context about prerequisites or exclusions.
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 of behavioral disclosure. It states 'Get details' which implies a read-only operation, but doesn't clarify permissions, rate limits, error handling, or what 'details' include (e.g., fields returned). For a tool with zero annotation coverage, this is insufficient to inform the agent adequately.
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 directly states the tool's purpose without any wasted words. It is appropriately sized and front-loaded, making it easy for an agent to parse quickly.
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 tool's low complexity (single parameter, no output schema, no annotations), the description is minimally adequate but lacks depth. It doesn't explain what 'details' are returned or potential behavioral aspects, which could be important for an agent to use it correctly in context with sibling tools.
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, with the 'id' parameter clearly documented as 'User ID'. The description adds no additional meaning beyond this, such as format examples or constraints, so it meets the baseline score where the schema does the heavy lifting.
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 verb ('Get') and resource ('details of a specific user'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_users' or 'search_all', which could also retrieve user information in different contexts, so it doesn't reach the highest score.
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 provides no guidance on when to use this tool versus alternatives like 'list_users' for multiple users or 'search_all' for broader searches. It lacks explicit context, prerequisites, or exclusions, leaving the agent to infer usage based on the tool name alone.
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 of behavioral disclosure. It states the tool retrieves chapters 'visible to the user', hinting at access control, but doesn't describe other traits like pagination behavior (implied by parameters but not explained), rate limits, authentication needs, or what 'visible' entails. For a list tool with zero annotation coverage, this is a significant gap in 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 a single, efficient sentence that front-loads the core purpose ('Get a listing of chapters') and adds a useful qualifier ('visible to the user'). There is zero waste, and every word earns its place, making it appropriately sized for a simple list tool.
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 tool's low complexity (a list operation), 100% schema coverage, and no output schema, the description is minimally adequate. It covers the basic purpose but lacks details on behavioral traits (e.g., pagination, visibility rules) and usage guidelines. With no annotations, it should do more to compensate, but it's not completely inadequate for a straightforward 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?
The input schema has 100% description coverage, with clear documentation for 'page', 'count', and 'sort'. The description adds no parameter-specific information beyond implying a listing operation. According to the rules, with high schema coverage (>80%), the baseline is 3 even with no param info in the description. This is met, but no extra value is provided.
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 ('Get a listing') and resource ('chapters'), specifying that it retrieves chapters 'visible to the user'. It distinguishes from siblings like 'get_chapter' (singular) and 'list_books' (different resource), though it doesn't explicitly contrast with 'search_all' which might overlap. The purpose is specific but could be more precise about scope versus alternatives.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer 'list_chapters' over 'get_chapter' (for single chapter) or 'search_all' (for broader queries), nor does it specify prerequisites or exclusions. Usage is implied by the verb 'Get a listing', but explicit context is missing.
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?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states it's a read operation ('Get'), but doesn't disclose pagination behavior (implied by parameters), rate limits, authentication needs, or what 'gallery' refers to contextually. This leaves significant gaps for a tool with 4 parameters.
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 with zero wasted words. It's front-loaded with the core purpose ('Get a listing of images'), making it immediately scannable and appropriately sized for a list operation tool.
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 4 parameters with full schema coverage but no annotations or output schema, the description is minimally complete. It identifies the resource and action, but lacks context about the gallery system, return format, error handling, or how it fits with siblings. This is adequate for basic understanding but has clear gaps in a rich tool ecosystem.
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 parameters are well-documented in the schema itself. The description adds no additional parameter semantics beyond implying a 'gallery' context for 'filter_type', but doesn't explain what 'gallery' vs 'drawio' means or provide usage examples. This meets the baseline for high schema coverage.
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 verb 'Get' and resource 'listing of images in the gallery', making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_image' (singular retrieval) or 'search_all' (broader search), which would require explicit comparison to achieve a perfect score.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention siblings like 'get_image' for single images, 'search_all' for cross-resource searches, or 'list_attachments' for other list operations, leaving the agent to infer usage context without explicit direction.
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 of behavioral disclosure. It states 'Get a listing' which implies a read-only operation, but doesn't mention pagination behavior (implied by parameters), rate limits, authentication needs, or what 'visible to the user' means in practice. For a tool with no annotations, this leaves significant behavioral 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, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, with every word contributing to understanding the core function.
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 annotations, no output schema, and 100% schema coverage, the description is minimally adequate but incomplete. It covers the basic purpose but lacks details on behavior, usage context, and output format. For a list tool with no annotations, it should do more to compensate for missing structured data.
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 schema already documents all three parameters (page, count, sort) with basic descriptions. The description adds no additional meaning about parameters, such as default values, constraints, or how they interact. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('listing of shelves'), making the purpose understandable. However, it doesn't distinguish this from other list_* tools (like list_books, list_pages) beyond specifying 'shelves', nor does it clarify what 'visible to the user' entails compared to other tools. This is clear but lacks sibling differentiation.
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 provides no guidance on when to use this tool versus alternatives like list_books, list_pages, or search_all. It mentions 'visible to the user' but doesn't explain how this differs from other list tools or when to choose one over another. There's no explicit when/when-not or alternative recommendations.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the consequence ('users with this role will lose it'), which is a critical behavioral trait, but fails to address other important aspects such as permissions required, whether the action is reversible, error conditions, or what happens to content owned by the role. This leaves significant gaps for a destructive 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 is a single, efficient sentence that is front-loaded with the core action and includes essential consequence information. There is no wasted text, and it is appropriately sized for the tool's complexity.
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 destructive nature, lack of annotations, and no output schema, the description is incomplete. It mentions a key consequence but omits critical details like permissions, reversibility, error handling, and response format. For a mutation tool with significant impact, this is inadequate to ensure safe and correct 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?
The schema description coverage is 100%, so the schema already documents both parameters (id and migrate_ownership_id) adequately. The description does not add any additional meaning or context beyond what the schema provides, such as explaining the purpose of migrate_ownership_id in more detail. This meets the baseline for high schema 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 a role') and specifies the resource ('role'), with an explicit consequence ('users with this role will lose it') that distinguishes it from other delete operations like delete_user or delete_book. It uses a specific verb and resource, making the purpose unambiguous.
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 provides no guidance on when to use this tool versus alternatives, such as update_role or other deletion tools like delete_user. It lacks context on prerequisites, permissions, or scenarios where deletion is appropriate, leaving the agent to infer usage from the tool name alone.
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 full burden. It discloses the key behavioral trait that deletion 'moves to recycle bin' rather than permanent removal, which is valuable context beyond just 'delete'. However, it doesn't mention permissions needed, whether deletion can be undone, error conditions, or what the response looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise - a single sentence with no wasted words. It's front-loaded with the core action and includes important behavioral context in parentheses. Every element earns its place.
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 destructive operation with no annotations and no output schema, the description provides minimal but critical context about the recycle bin behavior. However, it lacks important details about permissions, error handling, confirmation requirements, or what happens to dependent resources. The completeness is adequate but has clear gaps for a mutation 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 description coverage is 100% with the single parameter 'id' documented as 'Chapter ID'. The description adds no additional parameter semantics beyond what the schema already provides. The baseline score of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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 'chapter', making the purpose unambiguous. It distinguishes from other delete operations by specifying it's for chapters, but doesn't differentiate from other chapter operations like update_chapter or export_chapter beyond the obvious verb difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing the chapter ID), when deletion is appropriate versus archiving, or what happens if the chapter doesn't exist. No sibling tool comparisons 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 provided, the description carries the full burden of behavioral disclosure. It clarifies that deletion 'moves to recycle bin', which is valuable context beyond a simple 'delete' verb, indicating the action might be reversible. However, it lacks details on permissions, error conditions, or confirmation requirements, leaving gaps 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 a single, efficient sentence that front-loads the core action ('Delete a page') and adds clarifying detail ('moves to recycle bin') without redundancy. Every word earns its place, making it easy to parse quickly.
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 deletion tool with no annotations and no output schema, the description is minimally adequate. It covers the basic action and clarifies the recycle bin behavior, but lacks details on return values, error handling, or integration with sibling tools, leaving the agent to infer or guess in some scenarios.
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 the single parameter 'id' documented as 'Page ID'. The description adds no additional parameter information beyond what the schema provides, such as format examples or validation rules. This meets the baseline for high schema coverage but doesn't enhance understanding.
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 ('Delete') and resource ('a page'), making the purpose immediately understandable. It distinguishes from siblings like 'delete_book' or 'delete_chapter' by specifying the resource type. However, it doesn't explicitly mention what distinguishes it from other deletion tools beyond the resource name.
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 provides no guidance on when to use this tool versus alternatives like 'delete_book' or 'delete_chapter', nor does it mention prerequisites or constraints. The agent must infer usage from the resource name alone, which is insufficient for informed tool selection.
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 discloses a key behavioral trait: deletion moves the shelf to a recycle bin rather than permanent removal, which is valuable context beyond just 'delete'. However, it doesn't cover other aspects like permissions needed, error conditions, or what happens to associated resources (e.g., books on the shelf).
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 with zero waste. It's front-loaded with the core action and includes essential behavioral detail (moves to recycle bin) without fluff. Every word earns its place, making it highly concise and well-structured.
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 tool's complexity (a destructive operation with no annotations and no output schema), the description is minimally adequate. It covers the basic action and a key behavioral nuance (recycle bin), but lacks details on permissions, side effects, or error handling. For a delete tool, more context would be beneficial, but it meets the minimum viable threshold.
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% for the single parameter 'id', so the schema already documents it fully. The description adds no additional meaning about the parameter, such as format examples or constraints. Baseline is 3 when schema does the heavy lifting, but no extra value is provided.
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 ('Delete') and resource ('a shelf'), making the purpose unambiguous. It distinguishes from siblings like 'delete_book' or 'delete_user' by specifying the resource type. However, it doesn't explicitly differentiate from 'update_shelf' or 'get_shelf' beyond the verb, which prevents a perfect score.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., shelf must exist), exclusions (e.g., cannot delete if in use), or compare with siblings like 'delete_book' or 'update_shelf'. Usage is implied by the verb but lacks explicit context.
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 of behavioral disclosure. It mentions searching across content types but lacks details on permissions, rate limits, pagination behavior (beyond what the schema covers), or what the search results include (e.g., relevance scoring, fields returned). For a search tool with no annotation coverage, this is a significant 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?
The description is a single, efficient sentence that front-loads the core purpose ('Search across all content types') without unnecessary words. Every part of the sentence contributes to understanding the tool's scope and target, making it appropriately sized and structured.
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 tool's moderate complexity (search across multiple types) and no output schema, the description is minimally complete but lacks depth. It specifies what is searched but not how results are returned or behavioral aspects like permissions. With no annotations and incomplete behavioral transparency, it falls short of being fully helpful for an agent.
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 schema already documents all parameters (query, page, count) with their types and descriptions. The description does not add any additional meaning beyond what the schema provides, such as search syntax or result formatting, meeting the baseline for high schema 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 specific action ('Search across') and the target resources ('all content types (books, chapters, pages, shelves) in BookStack'), making the purpose explicit. It distinguishes this tool from sibling tools that are primarily CRUD operations on individual resource types, as this is a cross-content search function.
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 implies usage by specifying 'all content types,' suggesting it should be used for broad searches rather than targeted ones. However, it does not explicitly state when to use this tool versus alternatives (e.g., individual list_* tools for specific types) or provide exclusions, leaving some ambiguity in context.
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 adds valuable context by specifying that deletion 'moves to recycle bin', indicating the action is reversible rather than permanent, which is crucial for understanding the tool's effect beyond the basic 'delete' verb.
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 and front-loaded, consisting of a single sentence that directly states the tool's purpose and key behavioral detail ('moves to recycle bin'). Every word earns its place with no wasted information.
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 deletion tool with no annotations and no output schema, the description is minimally adequate. It clarifies the reversible nature of deletion but lacks details on permissions, error conditions, or what happens post-deletion. Given the complexity and missing structured data, it could be more complete.
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%, with the single parameter 'id' documented as 'Book ID'. The description does not add any meaning beyond this, such as format or sourcing details, but the schema adequately covers the parameter, meeting the baseline for 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 specific action ('Delete') and resource ('a book'), distinguishing it from sibling tools like 'delete_chapter' or 'delete_user' by specifying the exact entity being deleted. It provides immediate understanding of what the tool does without 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?
The description offers no guidance on when to use this tool versus alternatives like 'update_book' or 'list_books', nor does it mention prerequisites such as needing the book ID. It lacks explicit context for selection among deletion tools or other operations.
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 of behavioral disclosure. It mentions the admin permission requirement, which is valuable context. However, it doesn't describe whether this deletion is permanent/reversible, what happens to user data, error conditions, or confirmation requirements - significant gaps for a destructive 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 is a single, efficient sentence that front-loads the core action ('Delete a user account') and follows with the critical constraint ('requires admin permissions'). Every word serves a purpose with zero wasted content.
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 destructive tool with no annotations and no output schema, the description provides basic purpose and permission context but lacks critical information about behavioral consequences, return values, error handling, and comparison to sibling deletion tools. It's minimally adequate but has clear 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 description coverage is 100%, so the schema already fully documents both parameters. The description doesn't add any parameter-specific information beyond what's in the schema. The baseline score of 3 reflects adequate but minimal value addition for 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 specific action ('Delete') and resource ('a user account'), distinguishing it from sibling tools like 'delete_book' or 'delete_page' which target different resources. It provides precise verb+resource pairing that leaves no ambiguity about what this tool does.
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 states 'requires admin permissions', providing clear context about when this tool can be used. However, it doesn't mention when NOT to use it (e.g., for soft deletion vs permanent deletion) or name specific alternatives among the many sibling deletion tools.
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:

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

Score Badge

Copy to your README.md:

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

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/lautarobarba/bookstack_mcp_server'

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