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 states the tool creates an attachment but doesn't disclose behavioral traits such as required authentication, rate limits, whether the operation is idempotent, what happens on failure, or the format of the response. 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.

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

The description is a single, efficient sentence that front-loads the core purpose ('Create a new attachment') and method ('by uploading a file or linking to an external URL'). There is zero waste, and every word earns its place.

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

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

Given the complexity of a creation tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral aspects (e.g., permissions, error handling), response format, and usage guidelines. 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.

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 thoroughly. The description adds minimal value by mentioning 'uploading a file or linking to an external URL,' which hints at the 'file' and 'link' parameters but doesn't provide additional semantics beyond what the schema specifies. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the action ('Create a new attachment') and the method ('by uploading a file or linking to an external URL'), which is specific and distinguishes it from sibling tools like delete, list, read, and update. However, it doesn't explicitly differentiate from similar creation tools (e.g., bookstack_images_create) 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.

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., required permissions), when to choose file upload vs. URL linking, or how it differs from other attachment-related tools like bookstack_images_create. Usage is implied but not explicitly stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates critical traits: the action is destructive ('Delete permanently') and irreversible ('cannot be undone'), which are essential for safe use. However, it lacks details on permissions, error conditions, or response format, leaving some behavioral aspects unclear.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core action and its irreversible nature without unnecessary words. Every part of the sentence serves a clear purpose, 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.

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

Given the tool's complexity (destructive deletion with no output schema and no annotations), the description is adequate but incomplete. It covers the irreversible nature well but lacks details on permissions, potential errors, or what happens upon success, which are important for a deletion tool in this context.

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

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

The schema description coverage is 100%, with the parameter 'id' fully documented as 'Attachment ID to delete'. The description does not add any additional meaning beyond this, such as format examples or constraints, so it meets the baseline for high schema coverage without compensating further.

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

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

The description clearly states the specific action ('Delete an attachment permanently') and identifies the resource ('attachment'), distinguishing it from siblings like 'bookstack_attachments_list' (list) or 'bookstack_attachments_update' (update). It uses precise language that leaves no ambiguity about the tool's function.

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

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

The description implies usage context through 'permanently (this action cannot be undone)', suggesting caution, but does not explicitly state when to use this tool versus alternatives like 'bookstack_recycle_bin_delete_permanently' or other deletion tools. No prerequisites or exclusions are mentioned, leaving usage guidance incomplete.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'pagination and filtering' but doesn't cover critical aspects like authentication requirements, rate limits, error conditions, or what 'visible to the authenticated user' entails (e.g., permission-based filtering). This leaves significant gaps for a list operation.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('List all attachments') and includes key features ('pagination and filtering options') without any wasted words. It's appropriately sized for its function.

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

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

Given no annotations and no output schema, the description is incomplete. It doesn't explain what the return values look like (e.g., attachment objects with fields), error handling, or authentication context. For a list tool with filtering, more behavioral context is needed to guide the agent effectively.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no additional semantic context beyond implying filtering exists, which is already covered in the schema. 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.

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

The description clearly states the action ('List all attachments') and resource ('attachments visible to the authenticated user'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'bookstack_images_list' or 'bookstack_attachments_read', 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.

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

The description mentions 'pagination and filtering options' but provides no guidance on when to use this tool versus alternatives like 'bookstack_search' or 'bookstack_attachments_read'. It lacks explicit when-to-use or when-not-to-use instructions, leaving the agent to infer context.

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

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

With no annotations provided, the description carries full burden but only states what the tool returns, not behavioral traits. It doesn't disclose whether this is a safe read operation, permission requirements, rate limits, error conditions, or response format details. The description is functional but lacks transparency about how the tool behaves.

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

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

The description is a single, efficient sentence that front-loads the core purpose. Every word earns its place with no redundancy or unnecessary elaboration, making it easy to parse quickly.

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

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

For a simple read operation with one parameter and no output schema, the description covers the basic purpose adequately. However, without annotations or output schema, it should ideally provide more context about return format, error handling, or authentication requirements to be fully complete for agent use.

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

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

Schema description coverage is 100% with one documented parameter ('Attachment ID to retrieve'), so the schema already provides complete parameter information. The description adds no additional parameter semantics beyond what's in the schema, maintaining the baseline score for high schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('details of a specific attachment'), including key outputs like 'download URL and metadata'. It distinguishes from the list tool by focusing on a single attachment, but doesn't explicitly differentiate from other read operations like books_read or pages_read.

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

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

The description implies usage when needing attachment details for a known ID, but provides no explicit guidance on when to use this versus alternatives like bookstack_attachments_list or other read tools. No prerequisites, exclusions, or sibling tool comparisons are mentioned.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool updates details or replaces file content, implying a mutation operation, but doesn't cover critical aspects like required permissions, whether changes are reversible, rate limits, or what happens to existing data not mentioned. 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.

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 words. It directly states what the tool does, making it easy for an agent to parse quickly. Every part of the sentence earns its place.

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

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

Given the tool's complexity (a mutation operation with 5 parameters), lack of annotations, and no output schema, the description is insufficient. It doesn't explain behavioral traits like permissions or side effects, and while the schema covers parameters, the overall context for safe and effective use is incomplete. A mutation tool without annotations requires more descriptive guidance.

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

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

The schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal value beyond the schema by mentioning 'name' and 'file content' as examples, but it doesn't provide additional syntax, format details, or constraints. This meets the baseline of 3 when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Update an attachment's details such as name or replace the file content.' It specifies the verb ('update'), resource ('attachment'), and scope ('details' and 'file content'). However, it doesn't explicitly differentiate from sibling tools like 'bookstack_attachments_create' or 'bookstack_attachments_read', which would be needed for a score of 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when-not-to-use scenarios, or direct comparisons to sibling tools like 'bookstack_attachments_create' or 'bookstack_attachments_delete'. This leaves the agent without contextual usage instructions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'track system activities and user actions,' hinting at read-only behavior, but doesn't explicitly state that it's a safe, non-destructive operation. It also omits details like rate limits, authentication needs, pagination behavior (beyond what the schema implies), or what the output looks like (e.g., format, fields). For a tool with no 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.

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

The description is a single, efficient sentence that front-loads the core purpose ('List audit log entries') and adds context ('to track system activities and user actions'). There's no wasted text, and it's appropriately sized for a list tool. However, it could be slightly more structured by explicitly separating purpose from usage context.

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

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

Given the tool's complexity (4 parameters with nested objects, no output schema, and no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavioral traits, output format, and usage guidelines. With no output schema, the description doesn't explain return values, which is a gap. It's complete enough to understand what the tool does but not how to use it effectively in context.

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

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

The schema description coverage is 100%, meaning all parameters are documented in the schema itself. The description adds no additional meaning about parameters beyond what the schema provides (e.g., it doesn't explain filter usage or sorting implications). According to the rules, with high schema coverage, the baseline score is 3, as the description doesn't need to compensate but also doesn't add value here.

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

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

The description clearly states the tool's purpose as 'List audit log entries to track system activities and user actions,' which includes a specific verb ('List') and resource ('audit log entries'). It distinguishes itself from sibling tools by focusing on audit logs rather than books, pages, users, or other resources. However, it doesn't explicitly differentiate from other list tools (e.g., 'bookstack_books_list') 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.

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., permissions), when it's appropriate (e.g., for monitoring or debugging), or how it compares to other tools like 'bookstack_search' or 'bookstack_system_info' for similar purposes. Usage is implied through the purpose 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.

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 'Create a new book,' implying a mutation operation, but does not cover critical aspects like required permissions, whether the creation is reversible, potential side effects, or error conditions. This leaves significant gaps in understanding the tool's behavior.

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

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

The description is a single, efficient sentence that directly states the tool's purpose and key parameters without any unnecessary words. It is front-loaded and wastes no space, 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.

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

Given the complexity of a creation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits, error handling, return values, and usage context. While it covers the basic action and parameters, it does not provide enough information for safe and effective use in a broader context.

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

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

The description lists the parameters ('name, description, tags, and template settings'), which aligns with the input schema. Since schema description coverage is 100%, the schema already documents all parameters thoroughly. The description adds minimal value beyond restating parameter names, meeting the baseline score of 3 for high schema coverage.

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

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

The description clearly states the action ('Create a new book') and specifies the resources involved ('with name, description, tags, and template settings'), making the purpose evident. However, it does not explicitly differentiate this tool from other creation tools like bookstack_chapters_create or bookstack_shelves_create, which would be needed for a score of 5.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as bookstack_books_update for modifying existing books or bookstack_books_list for viewing books. There is no mention of prerequisites, context, or exclusions, leaving usage unclear beyond the basic action.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively explains that deletion moves items to a recycle bin rather than permanent removal, which is crucial behavioral context not evident from the name alone. However, it doesn't mention permission requirements, rate limits, or error conditions.

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

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

The description is a single, efficient sentence that communicates the core action and important behavioral detail without any wasted words. It's front-loaded with the primary purpose and follows with clarifying context.

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

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

For a destructive operation with no annotations and no output schema, the description provides essential context about the recycle bin behavior. However, it doesn't mention what happens to associated content (chapters, pages) or whether deletion requires specific permissions. Given the single parameter and clear schema, it's mostly complete but could benefit from more behavioral detail.

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

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

The schema description coverage is 100%, with the single parameter 'id' clearly documented as 'Book ID to delete'. The description doesn't add any additional parameter semantics beyond what's in the schema, but since the schema is complete, the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Delete a book') and specifies the resource ('book'), distinguishing it from sibling tools like 'bookstack_books_update' or 'bookstack_books_list'. It also adds important context about the deletion behavior ('moves to recycle bin where it can be restored'), which helps differentiate it from permanent deletion tools like 'bookstack_recycle_bin_delete_permanently'.

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

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

The description implies usage for deleting books via ID, but doesn't explicitly state when to use this tool versus alternatives like 'bookstack_recycle_bin_delete_permanently' or 'bookstack_recycle_bin_restore'. It provides basic context (deletion with recovery option) but lacks explicit guidance on prerequisites or exclusions.

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

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

No annotations are provided, so the description carries full burden. It states the tool exports a book but doesn't disclose behavioral traits such as whether it's a read-only operation, what the output looks like (e.g., file download link, raw content), potential side effects (e.g., generating server load), or any authentication/rate limits. The description is minimal and lacks operational context.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('Export a book') and specifies key details (formats). There is no wasted verbiage or redundancy, making it 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.

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks completeness in usage guidelines, behavioral transparency, and output details. Without annotations or output schema, more context on what the export returns would be beneficial for an agent.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters (id and format with enum values). The description adds no additional meaning beyond what's in the schema, such as explaining what a 'Book ID' is or providing examples of format usage. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the action ('Export') and resource ('a book'), specifying the available formats. It distinguishes from siblings like 'bookstack_books_list' or 'bookstack_books_read' by focusing on export functionality, though it doesn't explicitly differentiate from similar export tools like 'bookstack_chapters_export' or 'bookstack_pages_export'.

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

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

No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites (e.g., needing an existing book ID), compare it to sibling export tools (e.g., for chapters or pages), or indicate any constraints like file size limits or processing time.

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

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: visibility based on authentication, pagination support, and filtering options. However, it omits details like rate limits, error handling, response format, or whether this is a safe read operation (though 'List' implies non-destructive). The description adds value but doesn't fully cover behavioral traits for a tool with no annotations.

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

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

The description is two sentences, front-loaded with the core purpose and followed by hierarchical context. Every word earns its place—no fluff or repetition. It efficiently conveys essential information in a compact form.

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

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

Given no annotations and no output schema, the description is moderately complete. It covers the tool's purpose and key behaviors but lacks details on response structure, error cases, or authentication requirements. For a list tool with filtering and pagination, more context on return values or limitations would be helpful, though the high schema coverage mitigates some gaps.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds marginal context by mentioning 'pagination and filtering options,' which aligns with the 'count,' 'offset,' and 'filter' parameters, but doesn't provide additional semantics beyond what the schema offers. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the verb ('List') and resource ('books'), and specifies scope ('visible to the authenticated user'). It distinguishes books as 'top-level containers in BookStack hierarchy,' which helps differentiate from other list tools like chapters or pages. However, it doesn't explicitly contrast with sibling tools like 'bookstack_shelves_list' or 'bookstack_search' for finding books.

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

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

The description implies usage for listing books with pagination and filtering, but provides no explicit guidance on when to use this tool versus alternatives like 'bookstack_search' or 'bookstack_shelves_list.' It mentions 'visible to the authenticated user,' which hints at access context, but lacks clear when/when-not instructions or named alternatives.

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

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

No annotations are provided, so the description carries full burden. It states this is a 'Get' operation, implying read-only behavior, but doesn't disclose other traits like authentication needs, rate limits, error conditions, or what happens if the ID is invalid. 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.

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 details of a specific book') and adds necessary scope ('including its complete content hierarchy'). There is zero waste or redundancy.

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

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

Given no annotations, no output schema, and a simple input schema, the description is minimally adequate. It covers the purpose and scope but lacks behavioral details (e.g., response format, error handling) and usage guidelines. For a read tool with 100% schema coverage, it's passable but could be more complete.

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

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

Schema description coverage is 100%, with one parameter ('id') clearly documented in the schema. The description adds no additional parameter semantics beyond implying the ID retrieves book details and hierarchy. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the verb ('Get details') and resource ('a specific book') with additional scope ('including its complete content hierarchy'). It distinguishes from sibling tools like 'bookstack_books_list' (which lists books) and 'bookstack_books_export' (which exports). However, it doesn't explicitly mention that this is a read operation vs. create/update/delete siblings, though that's implied.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a book ID), when not to use it (e.g., for listing books vs. reading one), or compare to siblings like 'bookstack_books_list' or 'bookstack_chapters_read'. Usage is implied but not explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation, implying mutation, but doesn't mention required permissions, whether changes are reversible, if it's idempotent, or what happens to existing fields not specified. The description lacks critical behavioral context for a mutation tool.

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

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

The description is a single, efficient sentence that directly states the tool's purpose. It's appropriately sized and front-loaded with the core action, though it could be slightly more structured by explicitly mentioning the required 'id' parameter.

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

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

For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain behavioral traits (e.g., permissions, side effects), response format, error handling, or how it interacts with sibling tools. The high schema coverage helps, but the description alone leaves significant gaps for an update operation.

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

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

The description lists updatable fields (name, description, tags, template settings), which aligns with some parameters in the schema. However, with 100% schema description coverage, the schema already documents all parameters thoroughly. The description adds minimal value beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description clearly states the action ('Update') and resource ('a book's details'), specifying the fields that can be updated (name, description, tags, template settings). It distinguishes from siblings like bookstack_books_create (create) and bookstack_books_read (read), but doesn't explicitly differentiate from bookstack_books_delete (delete) or other update tools like bookstack_chapters_update.

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

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing the book ID), when not to use it (e.g., for partial updates vs. full replacements), or how it relates to sibling tools like bookstack_books_create or bookstack_books_delete.

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

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

No annotations are provided, so the description carries full burden. It implies a write operation ('Create') but doesn't disclose behavioral traits such as required permissions, whether creation is idempotent, error handling, or rate limits. The description is minimal and lacks context beyond the basic action.

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

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

The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and includes key parameters without unnecessary details, making it easy to scan and understand quickly.

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

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

Given the complexity of a creation tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, side effects, or response format, 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.

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 lists fields (name, description, tags, priority) but doesn't add meaning beyond what the schema provides, such as explaining priority ordering or tag usage. 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.

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

The description clearly states the action ('Create a new chapter') and resource ('within a book'), with specific fields mentioned (name, description, tags, priority). It distinguishes from siblings like chapters_list or chapters_update by focusing on creation, though it doesn't explicitly contrast with other create tools (e.g., books_create).

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

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

No guidance on when to use this tool versus alternatives is provided. It doesn't mention prerequisites (e.g., needing an existing book), exclusions, or comparisons to siblings like chapters_update for modifications. The description only states what it does, not when it's appropriate.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it's destructive (deletes chapter and pages) but reversible (moves to recycle bin where it can be restored). This covers safety and reversibility, though it could add more context like permissions or side effects.

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

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

The description is a single, efficient sentence that front-loads the core action and adds crucial behavioral context (recycle bin). Every word earns its place with no redundancy or waste.

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

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

Given the tool's complexity (destructive operation), no annotations, and no output schema, the description is fairly complete. It covers the action, scope, and reversibility, but could improve by mentioning permissions, error handling, or confirmation prompts for better contextual understanding.

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

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

Schema description coverage is 100%, with the parameter 'id' clearly documented in the schema. The description does not add meaning beyond the schema, as it doesn't specify parameter details like format or constraints. 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.

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

The description clearly states the specific action ('Delete a chapter and all its pages') and distinguishes it from siblings like 'bookstack_chapters_update' or 'bookstack_recycle_bin_delete_permanently' by specifying the scope (chapter + pages) and the recycle bin behavior. It uses precise verbs and resources.

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

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

The description implies usage for deletion with a recycle bin option, but does not explicitly state when to use this versus alternatives like 'bookstack_recycle_bin_delete_permanently' for permanent deletion or 'bookstack_chapters_update' for modification. It provides some context but lacks explicit guidance on alternatives or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It mentions the export action and formats but lacks critical behavioral details: whether this is a read-only operation, if it requires specific permissions, what the output looks like (e.g., file download, content string), or any rate limits. The description is minimal and doesn't compensate for the lack of annotations.

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

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

The description is a single, efficient sentence that front-loads the core action. It wastes no words but could be slightly more structured (e.g., by explicitly listing formats). It's appropriately sized for a simple tool, though it lacks depth.

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

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

Given no annotations and no output schema, the description is incomplete. It doesn't explain the output (e.g., whether it returns a file, URL, or content), error conditions, or behavioral constraints. For an export tool with potential complexity (e.g., large chapters, format-specific behaviors), this leaves significant gaps for an AI agent.

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

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

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—it doesn't explain what a 'chapter ID' is or provide context for format choices. 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.

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 chapter and all its pages'), specifying the output formats. It distinguishes from sibling tools like 'bookstack_chapters_list' or 'bookstack_chapters_read' by focusing on export functionality, but doesn't explicitly differentiate from similar export tools like 'bookstack_books_export' or 'bookstack_pages_export'.

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

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing the chapter ID), compare with other export tools (e.g., 'bookstack_books_export'), or specify use cases like backup or sharing. The description only states what it does, not when to use it.

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

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

With no annotations provided, the description carries the full burden. It discloses that results are limited to 'visible to the authenticated user' (permissions context) and mentions pagination behavior. However, it doesn't describe rate limits, error conditions, response format, or whether this is a read-only operation (though 'List' implies it).

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

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

Two sentences with zero waste. The first sentence states the core purpose and key behavioral aspects. The second sentence provides essential domain context ('Chapters are organizational containers within books') that helps the agent understand the resource hierarchy.

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

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

For a list tool with 4 parameters, 100% schema coverage, but no annotations and no output schema, the description is adequate but has gaps. It covers the basic purpose and scope but doesn't address response format, error handling, or detailed behavioral constraints that would be helpful for an agent.

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

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

Schema description coverage is 100%, so the schema already fully documents all 4 parameters. The description adds minimal value beyond the schema by mentioning 'pagination and filtering options' generically, but doesn't provide additional semantic context about parameter usage or interactions.

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

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

The description clearly states the specific action ('List all chapters'), specifies the resource ('chapters'), and provides scope details ('visible to the authenticated user with pagination and filtering options'). It distinguishes from siblings like bookstack_chapters_read (which reads a single chapter) and bookstack_chapters_create/delete/update (which are mutation operations).

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

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

The description implies usage context through 'visible to the authenticated user' and mentions pagination/filtering capabilities, but doesn't explicitly state when to use this tool versus alternatives like bookstack_search or bookstack_books_list. No explicit exclusions or comparisons to sibling tools are provided.

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

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

No annotations are provided, so the description carries full burden. It states it's a read operation ('Get details'), which implies it's non-destructive, but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or response format. For a tool with no annotations, this leaves significant gaps in understanding how it behaves beyond basic purpose.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('Get details of a specific chapter') and adds necessary detail ('including all its pages and complete structure'). There is zero waste, and it's appropriately sized for a simple read tool.

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

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

Given the tool's low complexity (one parameter, no output schema, no annotations), the description is minimally adequate. It covers the purpose but lacks behavioral details and usage guidelines. Without annotations or output schema, more context on response format or constraints would improve completeness, but it's not entirely inadequate for a basic read operation.

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

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

Schema description coverage is 100%, with one parameter ('id') fully documented in the schema. The description adds no additional meaning beyond implying the parameter is for a 'specific chapter', which is already clear from the schema. Baseline is 3 since the schema does the heavy lifting, but no extra value is added.

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

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

The description clearly states the verb ('Get details') and resource ('a specific chapter'), including what details are retrieved ('including all its pages and complete structure'). It distinguishes from siblings like 'bookstack_chapters_list' (which lists chapters) and 'bookstack_chapters_read' (which reads a chapter), though it doesn't explicitly name alternatives. The purpose is specific but could be more distinct from other 'read' operations.

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

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

No explicit guidance on when to use this tool versus alternatives is provided. The description implies usage for retrieving a chapter's details, but it doesn't specify prerequisites (e.g., needing a chapter ID), exclusions, or compare to siblings like 'bookstack_chapters_list' or 'bookstack_pages_read'. Usage is implied from the purpose, but no actionable guidelines are given.

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

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

No annotations are provided, so the description carries full burden. It states 'Update' implying a mutation, but doesn't disclose behavioral traits like required permissions, whether changes are reversible, if it overwrites or merges fields, rate limits, or what happens to unspecified fields. The description mentions what can be updated but not how the update behaves, leaving significant 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.

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

The description is a single, efficient sentence with zero waste. It front-loads the purpose and lists key fields without unnecessary elaboration. Every word earns its place, making it easy to scan and understand quickly.

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

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

Given the tool's complexity (mutation with 7 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, side effects, or response format, and while schema coverage is high, the description adds little value beyond repeating parameter names. For a mutation tool, more context on safety and outcomes is needed.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description lists fields (name, description, tags, priority) that map to some parameters, adding minimal context about what can be updated. However, it doesn't explain semantics beyond the schema, such as interactions between fields (e.g., description vs description_html) or that 'tags' replaces existing ones (which is in the schema). Baseline 3 is appropriate as schema does heavy lifting.

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

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

The description clearly states the action ('Update') and resource ('a chapter's details') with specific fields mentioned (name, description, tags, priority). It distinguishes from siblings like 'bookstack_chapters_create' (create vs update) and 'bookstack_chapters_read' (read vs update), though not explicitly named. However, it doesn't fully differentiate from 'bookstack_chapters_delete' (update vs delete) beyond the verb.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a chapter ID), when not to use it (e.g., for creating new chapters), or refer to sibling tools like 'bookstack_chapters_create' for creation or 'bookstack_chapters_read' for viewing. Usage is implied by the verb 'Update' 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.

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 retrieves information, implying a read-only operation, but doesn't specify if it requires authentication, has rate limits, returns structured data, or handles errors. This leaves significant gaps in understanding how the tool behaves beyond its basic purpose.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the key action ('Get'), making it easy to parse, though it could be slightly more structured by explicitly mentioning the parameter usage.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavioral traits, usage context, and output format, which are important for an agent to invoke it correctly in a real-world scenario.

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

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

The input schema has 100% description coverage, with the parameter 'error_code' documented as 'Specific error code to get guidance for'. The description adds no additional semantic context beyond this, such as examples of error codes or format requirements. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose with the verb 'Get' and resource 'comprehensive error handling information and troubleshooting guides', making it specific and actionable. However, it doesn't explicitly differentiate from sibling tools like 'bookstack_help' or 'bookstack_usage_examples', which might also provide guidance, leaving some ambiguity about its unique role.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for error handling, or compare to siblings such as 'bookstack_help' for general assistance or 'bookstack_search' for finding related content, leaving the agent to infer usage scenarios.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool provides 'contextual guidance' but doesn't describe what that means in practice—e.g., whether it returns instructional text, examples, error resolutions, or structured advice. It also omits key behavioral traits like whether it's read-only, requires authentication, has rate limits, or affects system state. The description is too vague to inform an 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.

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

The description is a single, efficient sentence that front-loads the core purpose ('Interactive help system providing contextual guidance'). There's no wasted verbiage or redundancy. However, it could be slightly more structured by hinting at the tool's output or usage scenarios, but it remains appropriately concise for a simple help tool.

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

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

Given the lack of annotations and output schema, the description is incomplete for a tool with two parameters. It doesn't explain what the tool returns (e.g., text guidance, structured data), how it integrates with sibling tools, or behavioral aspects like safety or performance. For a help system, users need to know what kind of guidance to expect, but the description leaves this ambiguous, making it inadequate for full contextual understanding.

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

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

Schema description coverage is 100%, with both parameters ('topic' and 'context') well-documented in the schema, including an enum for 'topic.' The description adds no parameter-specific information beyond what the schema provides—it doesn't explain how 'topic' choices relate to guidance or how 'context' influences responses. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, but the description contributes no additional value.

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

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

The description clearly states the tool's purpose as 'Interactive help system providing contextual guidance for LLM tool usage,' specifying the verb ('providing guidance') and resource ('LLM tool usage'). It distinguishes itself from sibling tools, which are all CRUD operations for BookStack resources, by being a meta-tool for guidance rather than direct content manipulation. However, it doesn't specify what 'contextual guidance' entails (e.g., examples, explanations, troubleshooting).

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., use when confused about tool usage), exclusions (e.g., not for direct data operations), or refer to sibling tools like 'bookstack_usage_examples' or 'bookstack_error_guides' that might offer overlapping functionality. Usage is implied only through the general term 'guidance.'

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a creation/upload operation, implying mutation, but doesn't cover critical aspects like authentication requirements, rate limits, error handling, or what happens on success/failure. This is a significant gap for a mutation tool without 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.

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 and wastes no space, making it easy to parse quickly.

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

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

Given the complexity of a creation tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral traits, usage context, and expected outcomes, which are crucial for an agent to invoke this tool correctly in a real-world scenario.

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

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

The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema, such as explaining the 'gallery' vs 'drawio' types or the implications of 'uploaded_to'. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the action ('Create a new image') and resource ('by uploading an image file to the gallery'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like bookstack_images_update or bookstack_attachments_create, which would require more specific context about what distinguishes image creation from other creation operations.

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

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

No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites, such as authentication or permissions needed, nor does it compare with sibling tools like bookstack_images_list or bookstack_attachments_create. This leaves the agent without context for tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively discloses that the action is permanent ('cannot be undone'), which is a critical behavioral trait for a destructive operation. However, it does not mention other aspects like required permissions, error handling, or rate limits, leaving some gaps.

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

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

The description is a single, efficient sentence that front-loads the key information ('Delete an image permanently from the gallery') and adds a crucial warning ('this action cannot be undone') without any wasted words. Every part of the sentence serves a clear purpose.

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

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

Given the tool's complexity (a destructive operation with one parameter), no annotations, and no output schema, the description is reasonably complete. It covers the permanent nature of the deletion, which is essential, but could be more complete by addressing permissions or error scenarios, though it meets most needs for this context.

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

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

The schema description coverage is 100%, with the parameter 'id' clearly documented as 'Image ID to delete'. The description does not add any additional meaning beyond what the schema provides, such as format details or examples. With high schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly states the specific action ('Delete an image permanently from the gallery') and resource ('image'), distinguishing it from siblings like bookstack_images_create, bookstack_images_list, bookstack_images_read, and bookstack_images_update by focusing on deletion rather than creation, listing, reading, or updating.

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

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

The description implies usage for permanent deletion of images, but does not explicitly state when to use this tool versus alternatives like bookstack_recycle_bin_delete_permanently or bookstack_attachments_delete, nor does it provide exclusions or prerequisites. The context is clear but lacks explicit guidance on alternatives.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions pagination and filtering but doesn't describe important behaviors: whether this is a read-only operation, what authentication is required, rate limits, error conditions, or what the output format looks like. For a list tool with no 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.

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

The description is a single, efficient sentence that front-loads the core purpose. Every word contributes meaning, though it could be slightly more specific by mentioning 'BookStack gallery images' rather than just 'gallery'.

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

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

Given no annotations and no output schema, the description is incomplete for a tool with 4 parameters and filtering capabilities. It doesn't explain what information is returned about each image, how pagination works in practice, or any behavioral constraints. The agent would need to guess about the response format and operational details.

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

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

Schema description coverage is 100%, so the schema already fully documents all 4 parameters. The description adds minimal value beyond the schema by mentioning 'pagination and filtering options' which aligns with the count/offset and filter parameters, but doesn't provide additional semantic context about how these work together or practical usage examples.

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

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

The description clearly states the action ('List all images in the gallery') and resource ('images'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'bookstack_attachments_list' or 'bookstack_images_read', which would require mentioning it's specifically for gallery images with pagination/filtering capabilities.

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

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

The description mentions 'pagination and filtering options' which implies when to use this tool (for browsing/searching images), but provides no explicit guidance on when to choose this over alternatives like 'bookstack_search' or 'bookstack_images_read'. No prerequisites, exclusions, or comparison to sibling tools are stated.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions retrieving 'details including URLs and metadata,' which adds some context about what information is returned. However, it doesn't cover critical aspects like whether this is a read-only operation (implied but not stated), authentication requirements, rate limits, error handling, or pagination behavior, leaving significant gaps for a tool with no annotations.

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

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

The description is a single, efficient sentence that front-loads the key action and resource ('Get details of a specific image') and adds useful context ('including URLs and metadata'). There is no wasted wording, making it appropriately sized and well-structured for its purpose.

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

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

Given the tool's low complexity (single parameter, no output schema, no annotations), the description is adequate but has clear gaps. It covers the basic purpose and hints at return values ('URLs and metadata'), but without an output schema, it should ideally provide more detail on the response structure. The lack of behavioral transparency and usage guidelines reduces completeness for effective agent use.

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

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

The input schema has 100% description coverage, with the single parameter 'id' clearly documented as 'Image ID to retrieve.' The description adds minimal value beyond this by implying the parameter is used to specify 'a specific image,' but doesn't provide additional semantics like format constraints or examples. Baseline score of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the action ('Get details') and resource ('a specific image'), making the purpose understandable. However, it doesn't explicitly differentiate this read operation from other image operations like 'bookstack_images_list' or 'bookstack_images_update' among the siblings, which would require mentioning it retrieves a single image by ID rather than listing all images.

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

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

No guidance is provided on when to use this tool versus alternatives. For example, it doesn't specify that this is for retrieving a single image by ID, as opposed to 'bookstack_images_list' for listing all images or 'bookstack_images_update' for modifying an image. The description implies usage by stating 'Get details of a specific 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.

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 updates image details or replaces content, implying a mutation operation, but lacks critical behavioral details: it doesn't specify required permissions, whether changes are reversible, error conditions, or what happens to unspecified fields. 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.

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 front-loaded with the core purpose ('Update an image's details'), though it could be slightly more structured by separating the two update types (details vs. content replacement). Overall, it's concise and wastes no space.

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

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

Given the tool's complexity (a mutation operation with 4 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, side effects, or response format, which are crucial for safe and effective use. The description alone is inadequate for an agent to fully understand how to invoke this tool correctly in context.

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

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

Schema description coverage is 100%, meaning all parameters (id, name, image, uploaded_to) are documented in the schema. The description adds minimal value beyond the schema by mentioning 'name' and 'image content' as examples, but doesn't provide additional context like format constraints or usage nuances. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't significantly enhance parameter understanding.

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

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

The description clearly states the tool's purpose: 'Update an image's details such as name or replace the image content.' It specifies the verb ('update'), resource ('image'), and scope of updates ('details such as name or replace the image content'), which distinguishes it from siblings like bookstack_images_create or bookstack_images_delete. However, it doesn't explicitly differentiate from bookstack_attachments_update or other update tools beyond the image resource focus.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing image ID), exclusions (e.g., when to use bookstack_images_create instead for new images), or contextual cues. The agent must infer usage from the tool name and description alone, which is insufficient for clear decision-making.

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

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

With no annotations, the description carries full burden but provides minimal behavioral insight. It states it's a creation tool, implying mutation, but doesn't cover permissions needed, whether it's idempotent, error handling, rate limits, or what happens on success (e.g., returns a page ID). This leaves critical gaps for an agent to use it safely and effectively.

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

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

The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose and includes only essential details (content formats). No unnecessary words or structural issues.

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

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

For a creation tool with 7 parameters, no annotations, and no output schema, the description is inadequate. It lacks behavioral context (e.g., auth needs, response format), usage guidance, and doesn't compensate for the missing output schema. The agent would struggle to use this tool correctly without additional information.

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

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

Schema description coverage is 100%, so the schema fully documents all 7 parameters. The description adds no parameter-specific information beyond implying content formats (html/markdown), which is already clear in the schema. 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.

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 with content'), specifying the content formats (HTML or Markdown). It distinguishes from siblings like 'bookstack_pages_update' or 'bookstack_pages_delete' by focusing on creation, but doesn't explicitly differentiate from other creation tools like 'bookstack_books_create' 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.

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 prerequisites (e.g., needing a book or chapter parent), compare to other creation tools (e.g., 'bookstack_books_create'), or indicate scenarios where it's appropriate (e.g., adding documentation vs. uploading attachments).

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

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

With no annotations provided, the description carries the full burden. It discloses that deletion is not permanent (moves to recycle bin) and implies restorability, which are key behavioral traits. However, it lacks details on permissions, error conditions, or what happens if the ID is invalid, 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.

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 critical context ('moves to recycle bin where it can be restored') without any wasted words. Every part earns its place.

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

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

For a destructive tool with no annotations and no output schema, the description is minimal but covers the essential behavior (soft deletion). It lacks details on permissions, response format, or error handling, which are important for safe invocation. Given the complexity, it's adequate but has clear gaps.

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

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

Schema description coverage is 100%, so the schema already documents the 'id' parameter fully. The description adds no additional parameter semantics, but with only one parameter and high schema coverage, the baseline is elevated. It implicitly confirms the parameter's purpose by referencing 'Page ID to delete' in context.

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

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

The description clearly states the specific action ('Delete a page') and resource ('page'), distinguishing it from siblings like 'bookstack_pages_update' or 'bookstack_recycle_bin_delete_permanently'. It adds nuance by specifying that deletion moves the page to a recycle bin, which is not obvious from the tool name alone.

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

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

The description implicitly provides usage context by mentioning the recycle bin, suggesting this tool is for soft deletion rather than permanent removal. However, it does not explicitly state when to use this versus alternatives like 'bookstack_recycle_bin_delete_permanently' or provide prerequisites (e.g., required permissions).

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the export action and formats but doesn't describe what happens during export (e.g., file generation, download initiation, content transformation), whether authentication is required, rate limits, or what the output looks like. For an export tool 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.

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

The description is a single, efficient sentence that communicates the core functionality without unnecessary words. It's appropriately sized for a tool with two parameters and clear purpose. Every word earns its place.

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

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

For an export tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the export produces (file, content stream, download link), whether there are side effects, or what happens on success/failure. Given the complexity of export operations and lack of structured data, more behavioral context is needed.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters (id and format with enum values). The description mentions 'various formats' which aligns with the format parameter's enum, but adds no additional semantic meaning beyond what the schema provides. 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.

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'), and specifies the available formats. It distinguishes from other page tools (create, delete, list, read, update) by focusing on export functionality. However, it doesn't explicitly differentiate from sibling export tools like bookstack_books_export and bookstack_chapters_export.

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

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

No guidance is provided about when to use this tool versus alternatives. The description doesn't mention prerequisites, permissions needed, or when to choose this over other export tools (books_export, chapters_export). It simply states what the tool does without context about appropriate usage scenarios.

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

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

With no annotations, the description carries full burden. It mentions visibility ('visible to the authenticated user'), which is useful for permissions context, but lacks other behavioral details: no rate limits, no pagination behavior beyond parameters, no error handling, no output format hints. It's minimal for a list tool with filtering.

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

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

The description is a single, efficient sentence that front-loads the core purpose. It avoids redundancy and wastes no words. However, it could be slightly more structured by separating key features (e.g., 'List pages with pagination, filtering, and visibility constraints').

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

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

Given 4 parameters with 100% schema coverage but no annotations and no output schema, the description is adequate but incomplete. It covers the basic purpose and hints at visibility constraints, but lacks guidance on usage, behavioral details, and output expectations. For a list tool with filtering, more context would be helpful.

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

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

Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds marginal value by mentioning 'pagination and filtering options', which aligns with count/offset and filter parameters, but doesn't provide additional semantics beyond what the schema already explains. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('List') and resource ('pages visible to the authenticated user'), and mentions key features ('pagination and filtering options'). It distinguishes from other page tools (create, delete, export, read, update) by focusing on listing. However, it doesn't explicitly differentiate from other list tools like bookstack_books_list or bookstack_chapters_list.

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

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

The description provides minimal guidance—it implies usage when listing pages with pagination/filtering, but offers no explicit when-to-use rules, prerequisites, or alternatives. It doesn't help an agent decide between this and other list tools (e.g., bookstack_search for broader searches).

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

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

No annotations are provided, so the description carries the full burden. It mentions retrieving 'full content' but does not disclose behavioral traits such as authentication requirements, rate limits, error handling, or whether it's a read-only operation (implied by 'Get' but not explicit). This leaves gaps for an agent to understand operational constraints.

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

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

The description is a single, efficient sentence that front-loads the core action ('Get details') and specifies key details (content formats). There is no wasted verbiage, 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.

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 covers the basic purpose but lacks context on usage guidelines and behavioral transparency, which are important for an agent to operate effectively in this environment with many sibling tools.

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

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

Schema description coverage is 100%, with the parameter 'id' clearly documented. The description does not add meaning beyond the schema (e.g., it doesn't explain where to obtain the ID or format specifics), 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.

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 the resource 'a specific page', specifying the content formats (HTML and Markdown). It distinguishes from siblings like 'bookstack_pages_list' (which lists pages) and 'bookstack_pages_update' (which modifies pages), but does not explicitly mention sibling differentiation.

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

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

No guidance is provided on when to use this tool versus alternatives. For example, it does not mention using 'bookstack_pages_list' to find page IDs first or clarify if this is for detailed content retrieval versus metadata-only reads from other tools.

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

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

With no annotations provided, the description carries full burden. It mentions 'update' and 'moving between books/chapters' which implies mutation, but doesn't disclose behavioral traits like required permissions, whether changes are reversible, rate limits, or what happens to unspecified fields. The description is minimal and lacks crucial operational context.

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

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

The description is a single, efficient sentence that front-loads the core purpose and includes the key additional capability. Every word earns its place with zero waste.

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

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

For a mutation tool with 8 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what happens when only some fields are provided, whether the operation is idempotent, what permissions are needed, or what the response contains. The description should provide more operational context.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'update' and specifies the resource 'page's details and content', including the specific capability of 'moving between books/chapters'. It distinguishes from siblings like bookstack_pages_create (create) and bookstack_pages_read (read-only).

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

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

The description implies usage for updating existing pages, but doesn't explicitly state when to use this versus alternatives like bookstack_pages_create for new pages or bookstack_pages_read for viewing. No guidance on prerequisites or exclusions is provided.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'Get[s] permission settings', implying a read-only operation, but doesn't clarify authentication requirements, rate limits, error conditions, or the format of returned data. This leaves significant gaps for an agent to understand how to use it effectively.

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

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

The description is a single, efficient sentence that front-loads the core action ('Get permission settings') and specifies the target without unnecessary words. It earns its place by clearly stating the tool's function in a compact form.

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

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

Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the permission settings include (e.g., roles, access levels), how results are structured, or potential errors. For a tool with no structured behavioral hints, more detail is needed to guide an agent adequately.

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

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

The schema description coverage is 100%, with both parameters clearly documented in the input schema (content_type with enum values and content_id as an integer). The description adds minimal value by listing content types but doesn't provide additional context like ID sourcing or permission implications beyond what the schema already covers.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('permission settings for specific content'), and identifies the content types (books, chapters, pages, or shelves). However, it doesn't explicitly differentiate from its sibling 'bookstack_permissions_update', which handles permission modifications rather than reading.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., authentication needs), compare it to sibling tools like 'bookstack_permissions_update' for modifications, or specify scenarios where reading permissions is appropriate (e.g., before making changes).

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

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

No annotations are provided, so the description carries full burden. It states 'update' implying a mutation, but doesn't disclose behavioral traits such as required permissions, whether changes are reversible, rate limits, or error handling. The description adds minimal context beyond the basic action, leaving gaps in safety and operational details for a tool that modifies access controls.

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

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

The description is a single, efficient sentence that front-loads the core action ('update permission settings') and purpose. It avoids redundancy and waste, though it could be slightly more structured by separating usage context from the action. Overall, it's 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.

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

Given the tool's complexity (4 parameters with nested objects, no annotations, no output schema), the description is incomplete. It lacks details on behavioral aspects like authentication needs, side effects, or response format. For a mutation tool that controls access, this is inadequate—users need more context to use it safely and effectively.

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

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

Schema description coverage is 100%, so the schema fully documents all 4 parameters and their properties. The description adds no specific parameter semantics beyond what's in the schema (e.g., it doesn't explain interactions between 'fallback_permissions' and 'permissions'). Baseline 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.

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 ('permission settings for specific content') with the purpose of 'control user and role access.' It distinguishes from sibling tools like 'bookstack_permissions_read' by specifying an update action rather than read. However, it doesn't explicitly differentiate from other update tools (e.g., 'bookstack_books_update') beyond the permissions focus.

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

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing admin rights), exclusions, or comparisons to sibling tools like 'bookstack_permissions_read' for viewing permissions or other update tools for different content aspects. The description implies usage for access control but lacks contextual boundaries.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the destructive nature ('this action cannot be undone'), which is crucial for a permanent deletion tool. However, it doesn't mention other important behavioral aspects like required permissions, error conditions, or what happens if the deletion ID is invalid, leaving gaps 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.

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

The description is a single, efficient sentence that front-loads the core action ('permanently delete') and includes the critical warning about irreversibility. Every word serves a purpose with zero waste, making it easy to parse and understand quickly.

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

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

Given the tool's destructive nature and lack of annotations or output schema, the description is minimally complete. It covers the irreversible action but misses details like required permissions, error handling, or confirmation of deletion success. For a high-stakes operation with no structured safety hints, more contextual information would be beneficial.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter 'deletion_id' with its type and purpose. The description doesn't add any parameter-specific information beyond what's in the schema, but with only one parameter and complete schema coverage, this is acceptable. The baseline for high coverage is 3, but the simplicity of a single parameter justifies a 4.

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

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

The description clearly states the specific action ('permanently delete') and target resource ('an item from the recycle bin'), distinguishing it from sibling tools like 'bookstack_recycle_bin_list' and 'bookstack_recycle_bin_restore'. It uses precise language that leaves no ambiguity about what the tool does.

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

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

The description implies usage context by specifying 'from the recycle bin' and the irreversible nature, suggesting it should be used for final removal rather than temporary deletion. However, it doesn't explicitly state when to use this versus alternatives like 'bookstack_recycle_bin_restore' or standard delete tools, nor does it mention prerequisites like needing the deletion ID from list operations.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'pagination options' which hints at the count and offset parameters, but doesn't describe what the tool returns (format, structure), whether it requires authentication, rate limits, or what happens if the recycle bin is empty. This is inadequate 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.

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

The description is a single, efficient sentence that states the core purpose upfront with no wasted words. It's 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.

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

For a tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'deleted items' means in this context (what types of items?), what the return format looks like, or any error conditions. The agent would be left guessing about important behavioral aspects.

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

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

The description mentions 'pagination options' which aligns with the two parameters (count and offset), but doesn't add meaningful semantic details beyond what's already in the schema (which has 100% coverage). The baseline of 3 is appropriate since the schema fully documents the parameters.

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

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

The description clearly states the action ('List all deleted items') and resource ('in the recycle bin'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this from sibling tools like 'bookstack_recycle_bin_delete_permanently' or 'bookstack_recycle_bin_restore', 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.

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, permissions needed, or how it differs from other list tools in the system like 'bookstack_books_list' or 'bookstack_pages_list'.

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

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

No annotations are provided, so the description carries the full burden. It mentions the action ('Restore') but does not disclose critical behavioral traits such as required permissions, whether the restoration is reversible, potential side effects (e.g., if the original location no longer exists), or error handling. This leaves significant 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.

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 unnecessary words. It is front-loaded with the core action and outcome, making it easy for an AI agent to parse quickly.

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

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

For a mutation tool with no annotations and no output schema, the description is minimally adequate. It covers the basic purpose and parameter context but lacks details on behavioral aspects like permissions, side effects, or return values, which are important for safe and effective tool invocation.

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

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

The input schema has 100% description coverage, with the parameter 'deletion_id' clearly documented. The description adds context by specifying that the deletion ID comes 'from recycle bin list,' which helps the agent understand where to obtain this value, providing meaningful semantics beyond the schema's technical definition.

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

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

The description clearly states the specific action ('Restore') on a specific resource ('deleted item from the recycle bin') with a clear outcome ('back to its original location'). It distinguishes itself from sibling tools like 'bookstack_recycle_bin_delete_permanently' and 'bookstack_recycle_bin_list' by focusing on restoration rather than permanent deletion or listing.

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

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

The description implies usage context by mentioning 'deleted item from the recycle bin,' suggesting it should be used after listing items in the recycle bin. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to restore vs. delete permanently) or provide any prerequisites, leaving some ambiguity 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.

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 creation tool, implying mutation, but doesn't mention required permissions, potential side effects (e.g., impact on existing users), rate limits, or what the response looks like (since no output schema exists). This leaves significant 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.

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 for a creation tool, though it could be slightly more informative given the lack of annotations.

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

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

For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions needed, error handling, or response format, and while the schema covers parameters well, the overall context for safe and effective use is lacking.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value by listing 'display name, description, and permission settings,' which aligns with the schema but doesn't provide additional syntax or format details beyond what's in the structured fields.

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

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

The description clearly states the action ('Create') and resource ('new role'), specifying what fields can be configured (display name, description, permission settings). It distinguishes from sibling tools like bookstack_roles_list or bookstack_roles_update by focusing on creation, though it doesn't explicitly contrast with them.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., bookstack_roles_update for modifications) or any prerequisites (e.g., required permissions). The description implies usage for role creation 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.

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 the option to migrate users, which adds some context beyond a basic delete. However, it fails to cover critical aspects like permissions required, whether deletion is permanent or reversible, error conditions (e.g., if role doesn't exist), or side effects. For a destructive operation with zero annotation coverage, this is inadequate.

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

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

The description is a single, efficient sentence that front-loads the core action ('Delete a role') and adds necessary detail ('with option to migrate users to another role'). There is no wasted verbiage, 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.

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

Given the complexity of a deletion tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral traits (e.g., permanence, permissions), error handling, and what the tool returns. While concise, it doesn't provide enough context for safe and effective use by an AI agent.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('id' and 'migrate_ownership_id') clearly. The description adds minimal value by implying the optional migration feature but doesn't provide additional semantics (e.g., what happens if migration is omitted). Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the action ('Delete a role') and specifies the resource ('role'), making the purpose unambiguous. It distinguishes from sibling tools like 'bookstack_roles_list' or 'bookstack_roles_update' by focusing on deletion. However, it doesn't explicitly differentiate from 'bookstack_roles_delete' (itself) or other deletion tools in terms of scope, so it's not a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., role existence), exclusions (e.g., cannot delete default roles), or compare to other deletion tools (e.g., 'bookstack_users_delete'). Usage is implied by the action 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.

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 'pagination and filtering options', which hints at scalability and query capabilities, but fails to address critical aspects: whether this is a read-only operation (implied by 'List' but not explicit), potential rate limits, authentication requirements, or error handling. The description adds minimal context beyond the basic action.

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

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

The description is a single, efficient sentence that front-loads the core action ('List all roles in the system') and appends key features ('with pagination and filtering options'). There is no wasted verbiage or redundancy, making it highly concise and well-structured for quick comprehension.

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

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

Given the tool's moderate complexity (4 parameters with nested objects, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and hints at behavior but lacks details on authentication, error responses, or output format. Without annotations or output schema, the agent must rely on the schema and description, which together provide a functional but incomplete picture.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters (count, offset, sort, filter). The description adds no additional semantic meaning beyond stating 'pagination and filtering options', which merely echoes what the schema already specifies. This meets the baseline of 3, as 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.

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

The description clearly states the verb ('List') and resource ('all roles in the system'), making the purpose unambiguous. It distinguishes from sibling tools like 'bookstack_roles_read' (single role) and 'bookstack_roles_create' (creation). However, it doesn't explicitly differentiate from other list tools (e.g., 'bookstack_users_list'), though the resource specificity is sufficient.

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

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

No guidance is provided on when to use this tool versus alternatives. While the description implies it's for listing roles, it doesn't mention prerequisites (e.g., authentication), compare it to 'bookstack_search' for broader queries, or specify scenarios like administrative tasks. The agent must infer usage from the 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.

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 this is a read operation ('Get details'), implying it's non-destructive, but doesn't specify authentication requirements, rate limits, error conditions, or what happens if the role ID doesn't exist. For a 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.

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

The description is a single, efficient sentence that front-loads the core purpose. It avoids unnecessary words and directly communicates the tool's function, though it could be slightly more structured by explicitly mentioning the parameter requirement.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on usage context, behavioral traits, and output format, which would be helpful for an agent to invoke it correctly without structured annotations.

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

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

The schema description coverage is 100%, with the single parameter 'id' clearly documented as 'Role ID to retrieve'. The description doesn't add any additional meaning beyond what the schema provides, such as format examples or constraints, but the baseline score of 3 is appropriate given the schema fully covers the parameter.

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

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

The description clearly states the verb ('Get details') and resource ('a specific role'), specifying what information is retrieved ('including all its permissions and settings'). It distinguishes from the sibling 'bookstack_roles_list' by focusing on a single role rather than listing multiple roles, but doesn't explicitly mention this distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'bookstack_roles_list' or 'bookstack_permissions_read'. It doesn't mention prerequisites, such as needing a role ID, or contextual factors like when detailed role information is required versus just a list.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is an update operation, implying mutation, but doesn't describe what happens on success/failure, whether changes are reversible, permission requirements, rate limits, or side effects. 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.

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

The description is a single, efficient sentence that front-loads the core action and key fields. It avoids unnecessary words and gets straight to the point. However, it could be slightly more structured by explicitly listing all updatable aspects or adding brief context.

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

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

Given the complexity (6 parameters with nested objects, no output schema, and no annotations), the description is incomplete. It doesn't explain the return values, error conditions, or behavioral nuances needed for a mutation tool. With no annotations to cover safety or side effects, the description should do more to compensate.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description lists some updatable fields (name, description, permission settings), which aligns with parameters like 'display_name', 'description', and 'permissions', but doesn't add meaningful semantics beyond what the schema provides. With high coverage, the baseline is 3.

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

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

The description clearly states the action ('Update') and resource ('a role's details'), specifying what fields can be updated (name, description, permission settings). It distinguishes from sibling tools like 'bookstack_roles_create' (creation) and 'bookstack_roles_delete' (deletion), but doesn't explicitly differentiate from 'bookstack_permissions_update', which might handle permissions separately. The purpose is clear but could be more specific about scope.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing role ID), when not to use it (e.g., for creating new roles), or refer to sibling tools like 'bookstack_roles_create' or 'bookstack_permissions_update'. Usage is implied by the verb 'Update', but explicit context is lacking.

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

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

With no annotations, the description carries full burden but provides minimal behavioral insight. It mentions 'advanced search syntax' but doesn't disclose performance characteristics, rate limits, authentication needs, or what the search returns (e.g., result format, pagination behavior beyond schema). This is inadequate for a search 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.

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

The description is a single, efficient sentence with zero waste. It front-loads the core purpose ('Search across all content types in BookStack') and adds only essential context ('using advanced search syntax').

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

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

For a search tool with no annotations and no output schema, the description is incomplete. It lacks information on return values (e.g., result structure, error handling), behavioral traits like rate limits or permissions, and usage context relative to sibling tools. The schema covers inputs well, but overall context is insufficient.

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

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

Schema description coverage is 100%, so the schema fully documents parameters. The description adds no additional parameter semantics beyond implying the query supports advanced syntax, which is already covered in the schema's description of the 'query' field. 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.

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

The description clearly states the action ('Search across all content types') and resource ('BookStack'), specifying it uses 'advanced search syntax'. It distinguishes from siblings like list operations by focusing on cross-content search, though it doesn't explicitly contrast with specific alternatives like 'bookstack_pages_list'.

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

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

No guidance is provided on when to use this tool versus alternatives. The description mentions 'advanced search syntax' but doesn't specify scenarios where this is preferable over filtered list operations (e.g., 'bookstack_pages_list'), nor does it mention prerequisites or exclusions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves information, implying a read-only operation, but doesn't clarify aspects like authentication requirements, rate limits, response format, or potential side effects. For a tool with no annotation coverage, this leaves significant gaps in understanding how it behaves.

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

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

The description is a single, efficient sentence that front-loads the core purpose. It avoids redundancy and waste, clearly stating what the tool does. However, it could be slightly more structured by explicitly listing the sections or providing a brief example, but it remains appropriately concise for its purpose.

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

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

Given the tool's complexity (low, with one optional parameter) and the absence of annotations and output schema, the description is minimally adequate. It covers the basic purpose but lacks details on behavioral traits, usage context, and output format. For a tool that provides 'comprehensive' information, the description should do more to guide the agent on what to expect from the response.

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

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

The input schema has 100% description coverage, with the 'section' parameter fully documented via enum and description. The description adds no parameter-specific details beyond what the schema provides, such as explaining the content of each section. 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.

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 comprehensive server information including capabilities, tools, resources, and usage guidance for LLM interaction.' It specifies the verb ('Get') and resource ('server information') with details about what information is included. However, it doesn't explicitly differentiate from sibling tools like 'bookstack_system_info' or 'bookstack_help', which might provide overlapping or related information.

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

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

The description provides no guidance on when to use this tool versus alternatives. It mentions retrieving 'server information' but doesn't specify scenarios, prerequisites, or exclusions. With many sibling tools (e.g., 'bookstack_system_info', 'bookstack_help'), the lack of comparative context leaves the agent guessing about appropriate usage.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a creation tool, implying a write operation, but doesn't cover important aspects like required permissions, whether it returns the created shelf ID, error conditions, or rate limits. This leaves significant 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.

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 and key parameters without any fluff. It's appropriately sized and front-loaded with the essential information.

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

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

For a creation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens upon success (e.g., returns shelf ID), error handling, or behavioral constraints like permissions. Given the complexity of a write operation, more context is needed.

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

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

Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description mentions name, description, and tags, which aligns with the schema but doesn't add meaning beyond it (e.g., it omits description_html and books). 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.

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

The description clearly states the action ('Create a new bookshelf') and specifies the key attributes (name, description, tags), which distinguishes it from other shelf operations like delete, list, read, or update. However, it doesn't explicitly differentiate from other 'create' tools (e.g., bookstack_books_create) 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.

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 prerequisites (e.g., permissions), when not to use it, or how it relates to sibling tools like bookstack_shelves_update or bookstack_books_create for adding books later.

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

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

With no annotations provided, the description carries the full burden. It discloses that this is a destructive operation ('Delete') and clarifies that books are not deleted, only removed from the shelf, which adds useful context about side effects. However, it lacks details on permissions, error handling, or confirmation steps, leaving 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.

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 bookshelf') and adds a clarifying note without redundancy. 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.

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 is minimally adequate. It clarifies the deletion scope (books are not deleted), but lacks details on permissions, return values, or error conditions, which are important for safe invocation in this context.

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

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

Schema description coverage is 100%, with the parameter 'id' fully documented in the schema. The description does not add any additional meaning or context beyond what the schema provides, 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.

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

The description clearly states the specific action ('Delete a bookshelf') and resource ('bookshelf'), distinguishing it from siblings like bookstack_shelves_update or bookstack_shelves_list. It also clarifies the scope by noting that books are not deleted, only removed from the shelf, which adds precision.

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

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

No explicit guidance on when to use this tool versus alternatives is provided. It doesn't mention prerequisites (e.g., needing the shelf ID), exclusions, or compare to other deletion tools like bookstack_books_delete, 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.

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

With no annotations provided, the description carries full burden. It discloses key behaviors: visibility is limited to authenticated user, pagination is supported, and filtering options exist. However, it doesn't mention rate limits, authentication requirements beyond 'authenticated user', error conditions, or response format details.

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

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

Two sentences with zero waste. First sentence states purpose and key features. Second sentence provides helpful context about what shelves are. Perfectly front-loaded and appropriately sized.

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

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

For a list operation with 100% schema coverage but no annotations or output schema, the description provides adequate context about scope and capabilities. It could be more complete by mentioning response format or typical use cases, but covers the essential purpose and constraints well given the available structured data.

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

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

Schema description coverage is 100%, so the schema fully documents all 4 parameters. The description adds minimal value beyond the schema by mentioning 'pagination and filtering options' which aligns with count/offset and filter parameters, but doesn't provide additional semantic context beyond what's in the parameter descriptions.

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

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

The description clearly states the action ('List all bookshelves'), specifies the resource ('bookshelves'), and provides scope ('visible to the authenticated user'). It distinguishes from siblings like bookstack_shelves_create/read/update/delete by focusing on listing rather than CRUD operations on individual shelves.

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

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

The description implies usage for listing shelves with pagination/filtering, but doesn't explicitly state when to use this tool versus alternatives like bookstack_search or bookstack_books_list for finding content. No explicit exclusions or prerequisites are mentioned.

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

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

No annotations are provided, so the description carries full burden. It implies a read-only operation ('Get details') but doesn't disclose behavioral traits like authentication requirements, rate limits, error handling (e.g., for invalid IDs), pagination for many books, or whether it returns nested book structures fully or partially. 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.

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 details of a specific bookshelf') and adds necessary elaboration ('including all its books and their structure'). There is zero waste or redundancy.

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

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

Given no annotations, no output schema, and 100% schema coverage, the description is minimally adequate but has clear gaps. It covers the basic purpose but lacks usage guidelines, behavioral details, and output information, which are important for a read operation that might return complex nested data.

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

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

Schema description coverage is 100%, with the parameter 'id' documented as 'Shelf ID to retrieve'. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. 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.

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

The description clearly states the action ('Get details') and resource ('a specific bookshelf'), including what details are retrieved ('including all its books and their structure'). It distinguishes from 'bookstack_shelves_list' by focusing on a single shelf rather than listing multiple shelves. However, it doesn't explicitly differentiate from 'bookstack_books_read' which might also provide book details.

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

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a shelf ID), compare with 'bookstack_shelves_list' for browsing shelves, or specify use cases like retrieving shelf contents for navigation or auditing.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions what fields can be updated but doesn't describe important behavioral aspects: whether this requires specific permissions, if changes are reversible, what happens to existing data not mentioned (e.g., does it preserve other fields?), or what the response looks like. For a mutation tool with zero annotation coverage, this is inadequate.

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

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

The description is a single, efficient sentence that states the core purpose upfront. It lists the key fields that can be updated without unnecessary elaboration. However, it could be slightly more structured by explicitly mentioning the required 'id' parameter or separating field categories.

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

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

For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects (permissions, side effects, response format) or provide usage guidance. While the schema covers parameters well, the description fails to compensate for the lack of annotations and output information that would help an agent understand the full context of this update operation.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description lists the updatable fields (name, description, tags, book collection) which aligns with parameters in the schema, but doesn't add meaningful semantic context beyond what the schema provides. The baseline 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.

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

The description clearly states the action ('Update') and resource ('a bookshelf's details'), specifying the fields that can be modified (name, description, tags, book collection). It distinguishes from sibling tools like 'bookstack_shelves_create' (create) and 'bookstack_shelves_delete' (delete), but doesn't explicitly differentiate from 'bookstack_shelves_read' or other update tools in the system.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing shelf ID), when not to use it (e.g., for creating new shelves), or refer to sibling tools like 'bookstack_shelves_create' for initial creation or 'bookstack_shelves_read' to check current details first.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves information, implying a read-only operation, but doesn't specify details like authentication requirements, rate limits, or what 'comprehensive system information' entails. This leaves significant gaps for a 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.

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 comprehensive system information') without any wasted words. It's appropriately sized for a no-parameter tool.

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

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

For a no-parameter tool with no output schema, the description is minimally adequate but lacks details on what 'comprehensive system information' includes or how it differs from 'bookstack_server_info'. Without annotations or output schema, more context on the return value would be helpful for the agent.

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

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

The tool has 0 parameters with 100% schema description coverage, so no parameter information is needed in the description. The description appropriately avoids discussing parameters, earning a baseline score of 4 for not adding unnecessary details.

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

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

The description clearly states the action ('Get') and resource ('system information about the BookStack instance'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from the sibling tool 'bookstack_server_info', which appears to serve a similar purpose, 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.

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 the sibling 'bookstack_server_info'. There's no mention of prerequisites, context, or exclusions, leaving the agent to 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.

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 mentions 'detailed information' but doesn't disclose behavioral traits like whether this is a read-only operation, if it requires authentication, rate limits, or what format the output takes. This leaves significant gaps in understanding how the tool behaves beyond its basic purpose.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action, making it easy to parse, though it could be slightly more specific to improve clarity.

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

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

Given the complexity (a tool with one parameter but no output schema or annotations), the description is incomplete. It doesn't explain what 'detailed information' entails, the return format, or any behavioral context, which is inadequate for an informational tool that might guide usage of other tools in the system.

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

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

The input schema has 100% description coverage, with the parameter 'category' clearly documented as 'Specific category to get detailed info about' and an enum list. The description adds no additional meaning beyond this, so it meets the baseline 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.

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

The description states the tool 'Get detailed information about tool categories and their specific use cases', which provides a clear verb ('Get detailed information') and resource ('tool categories'). However, it doesn't distinguish this from potential sibling tools like 'bookstack_help' or 'bookstack_error_guides' that might also provide informational content, making it somewhat vague about its specific niche.

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

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

The description offers no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for selecting a category, or how it differs from other informational tools in the sibling list, leaving the agent without explicit usage instructions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves examples but doesn't clarify if this is a read-only operation, whether it requires authentication, what format the examples are in (e.g., text, structured data), or if there are any rate limits. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior and constraints.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('Get step-by-step workflow examples') without unnecessary details. It uses clear language and avoids redundancy, making it easy to parse quickly. Every word earns its place in conveying the tool's intent.

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

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

Given the tool's low complexity (one parameter with full schema coverage) and lack of annotations or output schema, the description is minimally adequate. It explains what the tool does but doesn't address behavioral aspects like safety or output format. For a simple informational tool, this might suffice, but it leaves room for improvement in guiding agent usage.

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

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

The input schema has 100% description coverage, with a single parameter 'workflow' fully documented via an enum of specific workflows. The description mentions 'common BookStack operations,' which aligns with the enum values but doesn't add meaningful semantics beyond what the schema provides. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate for any gaps.

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

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

The description clearly states the tool's purpose as 'Get step-by-step workflow examples for common BookStack operations,' which specifies the verb ('Get') and resource ('workflow examples'). It distinguishes itself from sibling tools that perform CRUD operations on BookStack entities by focusing on guidance rather than direct manipulation. However, it doesn't explicitly differentiate from other informational tools like 'bookstack_error_guides' or 'bookstack_help' beyond the 'workflow examples' focus.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing to understand BookStack basics, or suggest using it for learning purposes before performing operations with sibling tools. Without explicit usage context, agents must infer its role from the 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.

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 creating a user account but fails to describe critical behaviors: whether this requires admin permissions, if the user receives an email (only hinted via 'send_invite' parameter), what happens on duplicate emails, or the response format. This leaves significant 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.

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 main action, though it could be slightly more structured by separating core functionality from optional features.

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

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

For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., permissions, error handling), output format, and usage guidelines. Given the complexity of user creation, this leaves the agent under-informed about critical aspects.

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

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

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds minimal value by listing 'email, name, and role assignments' as key attributes, but this doesn't provide additional semantics beyond what's in the schema. The baseline score of 3 reflects adequate but not enhanced parameter understanding.

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

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

The description clearly states the action ('Create a new user account') and specifies key attributes ('with email, name, and role assignments'), making the purpose evident. However, it doesn't explicitly differentiate this tool from sibling tools like 'bookstack_users_update' beyond the obvious 'create' vs 'update' distinction, 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.

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 'bookstack_users_update' or 'bookstack_users_list', nor does it mention prerequisites (e.g., required permissions) or contextual constraints. It merely states what the tool does without usage context.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool deletes a user account, implying a destructive, irreversible mutation, but doesn't specify critical details like required permissions, whether deletion is permanent or reversible, error conditions (e.g., if user doesn't exist), or what happens to migrated content. The migration option is mentioned but without behavioral context (e.g., what content is transferred).

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

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

The description is a single, efficient sentence that front-loads the core action ('Delete a user account') and adds a key feature ('with option to migrate content ownership'). There's no wasted verbiage, though it could be slightly more structured (e.g., separating primary action from optional behavior).

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

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

Given the tool's complexity (destructive mutation with 2 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, irreversibility, error handling, or response format, which are critical for safe invocation. The migration feature is mentioned but underspecified, leaving gaps in understanding the tool's full context.

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

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

Schema description coverage is 100%, with both parameters ('id' and 'migrate_ownership_id') documented in the schema. The description adds marginal value by implying 'migrate_ownership_id' is for transferring content ownership, but doesn't elaborate on semantics beyond what the schema provides (e.g., what 'content ownership' entails, default behavior if omitted). Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the action ('Delete a user account') and resource ('user account'), making the purpose immediately understandable. It distinguishes from sibling tools like 'bookstack_users_list' or 'bookstack_users_update' by specifying deletion. However, it doesn't explicitly differentiate from 'bookstack_users_delete' (itself) or other destructive operations like 'bookstack_recycle_bin_delete_permanently' in terms of scope.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., user must exist, permissions required), when not to use it (e.g., for temporary deactivation), or refer to related tools like 'bookstack_users_update' for modifications instead of deletion. The optional migration parameter hints at a use case 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.

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. While it mentions 'pagination and filtering options,' it fails to detail critical behaviors: it doesn't specify whether this is a read-only operation (implied but not stated), what permissions are required, how errors are handled, or the format of returned data (e.g., JSON structure). For a tool with no annotation coverage, this leaves significant gaps in understanding its operational characteristics.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('List all users in the system') and adds key features ('with pagination and filtering options') without unnecessary details. It avoids redundancy and waste, making it easy to parse. A slight deduction is due to the lack of structure (e.g., not separating purpose from guidelines), but it remains appropriately concise for its content.

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

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

Given the complexity (4 parameters with nested objects, no output schema, and no annotations), the description is minimally adequate. It covers the basic action and hints at capabilities but lacks depth: it doesn't explain return values (critical without an output schema), error conditions, or integration with sibling tools. While it meets a bare-minimum threshold, it doesn't fully address the tool's context, leaving the agent to infer too much from the schema alone.

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

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

The input schema has 100% description coverage, providing clear details for all parameters (count, offset, sort, filter). The description adds minimal value beyond the schema by mentioning 'pagination and filtering options,' which aligns with the schema but doesn't elaborate on syntax or usage nuances. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't compensate with additional semantic insights.

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

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

The description clearly states the action ('List all users') and resource ('users in the system'), making the purpose immediately understandable. It also mentions key capabilities ('pagination and filtering options'), which adds specificity. However, it doesn't explicitly differentiate from sibling tools like 'bookstack_users_read' (which likely retrieves a single user) or 'bookstack_users_create' (which creates users), leaving some ambiguity about when to choose this tool over alternatives.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'bookstack_users_read' for single-user retrieval or 'bookstack_search' for broader searches, nor does it specify prerequisites (e.g., authentication requirements) or typical use cases (e.g., administrative tasks). This lack of context could lead to misuse or inefficiency.

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

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

No annotations are provided, so the description carries full burden. It states this is a read operation ('Get details'), implying it's non-destructive, but doesn't disclose behavioral traits like authentication requirements, rate limits, error handling, or what happens if the user ID doesn't exist. For a tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.

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

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

The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose and includes relevant scope details. Every word earns its place without redundancy or unnecessary elaboration.

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

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

Given the tool's low complexity (single required parameter, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks context on usage, behavioral traits, or output format. Without annotations or output schema, the agent must infer behavior from the description alone, which is insufficient for full understanding.

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

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

Schema description coverage is 100%, with the single parameter 'id' fully documented in the schema as 'User ID to retrieve'. The description adds no additional parameter semantics beyond implying the tool retrieves details for a specific user, which is already clear from the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the verb ('Get details') and resource ('a specific user') with additional scope ('including their roles and permissions'). It distinguishes from sibling tools like 'bookstack_users_list' (which lists users) and 'bookstack_users_create/update/delete' (which modify users). However, it doesn't explicitly contrast with 'bookstack_permissions_read' which might overlap in permissions information.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a user ID), when not to use it, or how it differs from 'bookstack_users_list' for listing users or 'bookstack_permissions_read' for permissions. Usage is implied by the name and description but not explicitly stated.

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