Read spaces, collections, pages and content; search docs and manage GitBook organization spaces.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 3.9/5 across 14 of 14 tools scored.
Each tool targets a distinct resource and action (e.g., get vs list vs search, change-request vs page vs space), so there is no meaningful overlap or ambiguity between tools.
All tool names follow a consistent verb_noun pattern with a uniform gitbook_ prefix (e.g., gitbook_list_spaces, gitbook_get_page, gitbook_create_change_request). The naming is predictable and systematic.
14 tools is slightly high but still reasonable for a documentation platform API covering resources like spaces, pages, change requests, collections, organizations, and search. Each tool has a clear purpose, though the set feels a bit broad with several read-only operations.
The set is heavily read-focused and lacks essential write operations for pages and spaces (create, update, delete), which are core to GitBook's purpose. It does cover change-request lifecycle partially (create, list, update) but omits merge/delete and page editing, leaving noticeable gaps.
gitbook_create_change_requestCreate change requestACreate a new draft change request (branch) in a space. Safe: creates a draft; publishes nothing. GitBook REST: POST /spaces/{spaceId}/change-requests.
| Name | Required | Description | Default |
|---|---|---|---|
| spaceId | Yes | The space id. | |
| subject | No | A title/subject for the change request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Safe: creates a draft; publishes nothing,' but the annotations declare destructiveHint: true. This is a direct contradiction, indicating the tool may have destructive effects. Per the rubric, this scores 1 and triggers the annotation_contradiction flag.
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-loads the action, and includes the safety note and endpoint reference. Every sentence contributes useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two parameters and no output schema. The description gives purpose, safety, and endpoint, which is mostly sufficient. However, the contradiction between the 'Safe' claim and destructiveHint:true undermines confidence, and the description does not mention what the response will contain. A more complete description would reconcile this discrepancy.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents both spaceId and subject. The description adds minimal extra meaning beyond repeating the endpoint, which includes spaceId. It does not clarify the format or usage of subject beyond its schema description, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Create a new draft change request (branch) in a space.' It distinguishes this from sibling tools like 'update_change_request' and 'list_change_requests' by specifying 'draft' and 'publishes nothing'. The REST endpoint further clarifies the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (creating a draft change request) and includes the safety note 'Safe: creates a draft; publishes nothing.' However, it does not explicitly mention alternatives or when not to use it, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_get_collectionGet collectionAGet a collection by its ID. GitBook REST: GET /collections/{collectionId}.
| Name | Required | Description | Default |
|---|---|---|---|
| collectionId | Yes | The collection id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation. The description adds only the REST endpoint (GET /collections/{collectionId}), which provides minor technical context but does not disclose additional behavioral traits such as response structure, error handling, or prerequisites beyond the ID. The annotation covers the main safety aspect, so a baseline score is appropriate.
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 remarkably concise, consisting of two short sentences. The first sentence states the core purpose, and the second provides the REST endpoint. Every word contributes value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read tool with a single parameter and no output schema. The description sufficiently conveys the operation and the necessary input (collection ID). However, it does not mention potential return values or edge cases like 404 responses, but given the simplicity and annotation support, the context is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides a 100% description coverage with the single parameter 'collectionId' described as 'The collection id.' The tool description does not add any extra meaning or format details beyond what the schema already contains, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get a collection by its ID.' The verb 'Get' and resource 'collection' are specific, and the qualifier 'by its ID' differentiates this from sibling tools like list_collections, which would retrieve multiple collections.
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 implicit usage guidance by indicating the tool is for retrieving a single collection when its ID is known. However, it does not explicitly mention alternatives or scenarios where this tool should not be used, such as needing to list all collections, which would require list_collections.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_get_current_userGet current userAGet the profile of the authenticated GitBook user. GitBook REST: GET /user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds the 'authenticated' qualifier and the REST endpoint, which is useful context but does not disclose potential behaviors like error handling or response format. Given the annotation coverage, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the action and resource, the second provides the REST reference. Every word earns its place, with no redundancy or irrelevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with a clear purpose and no output schema, the description is fully complete. It tells the agent exactly what the tool does and even provides the REST endpoint, which is more than sufficient for invocation decisions.
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 zero parameters, and the input schema is empty. Per the rubric, 0 parameters earns a baseline of 4. The description adds no parameter information, but none is needed.
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 the resource ('profile of the authenticated GitBook user'), which is specific and distinct from sibling tools like get_space or get_page. Including the REST endpoint (GET /user) further reinforces the precise operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this tool when the authenticated user's profile is needed. No explicit exclusions or alternative mentions are provided, but the purpose is so distinct among siblings (no other tool covers this) that guidance is effectively implied. A 4 reflects clear context without explicit alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_get_pageGet pageAGet a single page's content from a space by its page ID. GitBook REST: GET /spaces/{spaceId}/content/page/{pageId}.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Response format — 'document' (structured, default) or 'markdown'. | |
| pageId | Yes | The page id. | |
| spaceId | Yes | The space id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the REST endpoint but no further behavioral insights (e.g., error handling, auth requirements, or rate limits). It does not contradict annotations, but beyond the safety hint, it adds little extra behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action. It includes the REST endpoint for reference without unnecessary fluff. Every word earns its place, making it 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 simplicity (single get operation, read-only hint, and complete schema), the description is adequately complete. It lacks only optional details like error responses, but for a simple read with good schema coverage, it does not need extensive additional context. The endpoint reference adds useful 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 input schema covers 100% of parameters with descriptions, including the format enum and required IDs. The description itself mentions 'by its page ID' but does not elaborate on the format parameter or add semantic meaning beyond what the schema already provides. Baseline 3 is appropriate since 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: 'Get a single page's content from a space by its page ID.' This distinguishes it from sibling tools like gitbook_list_pages (which lists pages) and gitbook_search_space (which searches). The verb 'Get' and resource 'page' with scope 'single' and 'by its page ID' provide precise purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by mentioning 'single page' and the need for a page ID, but there is no explicit guidance on when to use this tool versus alternatives like listing pages or searching. It does not mention exclusions or alternative tool names. The guidance is minimal and inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_get_spaceGet spaceAGet full details of a space by its ID. GitBook REST: GET /spaces/{spaceId}.
| Name | Required | Description | Default |
|---|---|---|---|
| spaceId | Yes | The space id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description confirms a read operation. It adds that the operation returns 'full details' and references the REST endpoint, but it does not disclose potential errors, response format, or rate limits. Given the simple read nature, this is acceptable but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary purpose and immediately followed by the REST endpoint. There is zero wasted text.
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 get-by-ID tool with one parameter, the description is largely sufficient. It states the resource, the identifier, and the REST endpoint. However, with no output schema, it could be more explicit about what 'full details' includes, but the context is strong enough for an agent 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?
The schema already provides a description for the single parameter spaceId ('The space id.'), giving 100% schema description coverage. The description adds no extra semantic detail beyond that, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Get full details of a space by its ID.' It specifies the resource (space) and the identifier (ID), and the REST endpoint adds precision. This effectively distinguishes it from sibling tools like gitbook_get_page or gitbook_get_collection.
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 you need full details of a single space by ID. However, it does not explicitly state when to use this over alternatives (e.g., listing spaces or searching). No exclusions or prerequisite conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_list_change_requestsList change requestsAList change requests for a space. GitBook REST: GET /spaces/{spaceId}/change-requests.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| limit | No | Results per page. | |
| status | No | Filter by change-request status, e.g. 'open', 'merged', 'draft'. | |
| spaceId | Yes | The space id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation. The description adds the REST endpoint, which is marginally useful, but does not disclose pagination behavior, filtering capabilities, or return format. No contradiction exists, yet the description carries minimal additional behavioral context beyond 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?
Two concise sentences with no wasted words. The description is front-loaded with the core purpose and includes a direct REST reference, making it efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, full schema coverage, and readOnlyHint annotation, the description is sufficiently complete for an agent to understand the operation. It includes the space-scoping context and the HTTP endpoint, covering essential details. Minor omissions like pagination defaults are already in the schema, so no significant gap exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for all parameters (page, limit, status, spaceId) already provided in the input schema. The description adds no parameter-specific detail, such as how status filtering behaves or default pagination, so it meets the baseline but does not exceed it.
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') and the resource ('change requests for a space'), with a specific endpoint reference. It differentiates from sibling tools like create/update change requests by focusing on retrieval.
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 change requests in a space but provides no explicit when-to-use guidance or alternatives. Context from siblings (create/update) suggests this is for read-only listing, but the description itself does not specify exclusions or preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_list_collectionsList collectionsAList all collections in an organization. GitBook REST: GET /orgs/{organizationId}/collections.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| limit | No | Results per page. | |
| nested | No | Include nested (sub-)collections in the response. | |
| organizationId | Yes | The organization id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description aligns by indicating a GET request. It adds the REST endpoint and scope but no additional behavioral details such as pagination defaults or nested collection handling. The annotation lowers the bar, and the description meets it without enriching further.
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 long, front-loaded with the core action and resource, and includes the REST endpoint reference. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with a fully documented schema and a read-only annotation, the description is adequate. It does not explain return values (no output schema exists), but the low complexity and clear resource scope make it sufficiently complete for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with meaningful descriptions for all four parameters (organizationId, page, limit, nested). The description does not need to repeat parameter details; the baseline of 3 is appropriate since the schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'collections' and scope 'in an organization.' It distinguishes from the sibling 'get_collection' by explicitly saying 'all collections,' making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context (listing collections within an organization) but does not explicitly explain when to use this tool versus alternatives like get_collection or list_spaces. Usage is implied from the resource name rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_list_commentsList commentsAList top-level comments posted on a space. GitBook REST: GET /spaces/{spaceId}/comments.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| limit | No | Results per page. | |
| status | No | Filter by comment status. | |
| spaceId | Yes | The space id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds the behavioral nuance that only 'top-level' comments are returned, which is useful context. However, it does not disclose behavior around pagination, sorting, or how the status filter affects results, so the added value is limited.
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 consists of two short, direct sentences. The first states the action and resource clearly, and the second provides the exact REST endpoint for reference. There is no fluff or redundancy, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with four parameters and no output schema, the description is adequate but not comprehensive. It clearly states the purpose and endpoint but does not describe the response shape, pagination defaults, or valid status values. The absence of an output schema and enum definitions means the agent must infer some details from the REST endpoint.
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% coverage, with all four parameters individually described. The description does not add any parameter-specific meaning beyond what the schema provides. It mentions the endpoint but not how parameters map to the request, so it relies on the schema for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'top-level comments' scoped to 'a space'. It directly states the REST endpoint, which unambiguously identifies the operation. Among siblings, this is the only comment-related tool, so there is no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear this tool is for listing top-level comments on a space, which implies when to use it. It does not explicitly name alternatives or exclusions, but since no sibling tool handles comments, the context is effectively unambiguous. A clear usage scenario is communicated without needing explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_list_organizationsList organizationsAList the organizations the authenticated user belongs to. GitBook REST: GET /orgs.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| limit | No | Results per page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares the safe read nature, and the description is consistent with it. It adds the authentication scope and endpoint but does not describe any additional behavioral traits like pagination behavior or rate limits. The description adds some context beyond annotations but not a lot.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the tool's purpose, followed by an endpoint reference. Every word earns its place with no waste or redundant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple list operation with two pagination parameters and no output schema. The description, combined with the schema and annotations, gives enough context for a low-complexity tool. It does not detail the return format, but given the lack of an output schema, the meaning is still reasonably clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for both page and limit, with schema description coverage at 100%. The description adds no additional parameter semantics, so a 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 verb 'list' plus the resource 'organizations' and specifies the scope ('the authenticated user belongs to'), distinguishing it from sibling list tools like list_spaces and list_collections. The endpoint reference adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context that this returns organizations for the authenticated user, which implies when to use it. However, it does not explicitly mention alternatives or when not to use it, so guidance is somewhat implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_list_pagesList pagesAList all pages in a space with their hierarchy and metadata. GitBook REST: GET /spaces/{spaceId}/content/pages.
| Name | Required | Description | Default |
|---|---|---|---|
| spaceId | Yes | The space id. | |
| computed | No | Include computed properties in the response. | |
| metadata | No | Include page metadata in the response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so safety is already known. Description adds hierarchy/metadata and REST endpoint, but no deeper behavioral context such as pagination or response size. Credit for added context beyond annotation.
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, both informative: purpose and REST endpoint. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple read-only list tool with high schema coverage and readOnlyHint. Description states purpose and endpoint. No output schema, but not required for simple list. Minor gap: no explicit pagination note, but low complexity keeps completeness high.
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?
Input schema covers 100% of parameters with descriptions for spaceId, computed, and metadata. Description adds no param-specific syntax beyond 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?
Description uses specific verb 'List' with resource 'pages in a space' and scope 'all pages', clearly distinguishing from sibling tools like gitbook_get_page (single page) and gitbook_list_spaces (all spaces).
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?
Clear context: use this when you need all pages in a space. Does not explicitly name alternatives or exclusions, so not a 5. Sibling tools imply alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_list_spacesList spacesAList all spaces in an organization. GitBook REST: GET /orgs/{organizationId}/spaces.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| limit | No | Results per page. | |
| organizationId | Yes | The organization id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds the REST endpoint, which is useful context, but it does not disclose pagination behavior (despite page/limit params) or any other behavioral details beyond the annotation.
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 concise sentences with no redundancy. The first sentence states the core purpose, and the second adds the REST endpoint reference. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with full schema coverage and readOnlyHint, the description is adequate. It does not mention the return format or pagination behavior, but these are inferable from the schema and the tool's nature. There is no output schema, so some additional detail could be given, but overall it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (organizationId, page, limit) are already documented. The description adds no additional parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('spaces'), and the scope ('in an organization'). It is differentiated from siblings like get_space (single) and search_space (search) by the explicit phrase 'all spaces' and the REST endpoint reference.
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 purpose is so explicitly stated that the use case is clear: list all spaces in an organization. However, it does not explicitly mention alternatives (e.g., get_space for a single space) or exclusions, so it lacks explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_search_organizationSearch organizationASearch content across an entire organization. GitBook REST: GET /orgs/{organizationId}/search.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| limit | No | Results per page. | |
| query | Yes | The full-text search query (required). | |
| organizationId | Yes | The organization id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds only marginal behavioral context: the REST GET endpoint and the org-wide scope. It does not disclose pagination behavior, result format, or any other operational traits. With annotations present, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The main action and scope are front-loaded, and the REST endpoint is a compact implementation detail. Excellent conciseness.
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 relative simplicity and the read-only annotation, the description is mostly adequate. However, it does not explain what content is searched (e.g., pages, docs) or what the response contains, which could leave an agent uncertain about the tool's output. Since there is no output schema, this gap prevents a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already well-documented in the schema. The description adds no additional parameter meaning beyond what the schema provides. Baseline 3 is appropriate 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 verb ('Search') and resource ('content across an entire organization'). It distinguishes from sibling 'gitbook_search_space' by emphasizing the organization-wide scope, making it unambiguous which tool to use for org-level searches.
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 phrase 'across an entire organization' clearly implies the use case of searching all content in an org, contrasting with space-specific searches. However, it does not explicitly name the alternative tool (gitbook_search_space) or state when not to use it, so it lacks an explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_search_spaceSearch spaceAFull-text search across all pages in a space. GitBook REST: GET /spaces/{spaceId}/search.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| limit | No | Results per page. | |
| query | Yes | The full-text search query (required). | |
| spaceId | Yes | The space id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds the scope ('across all pages in a space') and the underlying REST method, which provides useful context beyond annotations. However, it does not disclose pagination behavior, result format, or rate limits, so it does not exceed the minimal bar for additional behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: one stating the tool's function, and one providing the API endpoint. Every word contributes to clarity, with no filler or redundancy. It is front-loaded with the core purpose and keeps the technical reference concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is straightforward (search with pagination) and has full parameter documentation plus readOnlyHint. While there is no output schema, the description does not explain return values, but for a full-text search tool this is not a critical omission given the simplicity. The context is adequate for an agent to invoke it correctly, though a brief note on result structure would elevate completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all four parameters (spaceId, query, page, limit) are documented in the input schema. The description adds no new parameter-level information beyond what the schema already provides. The mention of 'full-text search' aligns with the query parameter's schema description, so it does not meaningfully 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 tool's function: 'Full-text search across all pages in a space.' It specifies a distinct verb ('search') and resource ('space'), and differentiates from sibling tools like search_organization by explicitly scoping to a space. The REST endpoint reference further anchors its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this searches within a specific space, implying when to use it (space-scoped search). However, it does not explicitly mention alternatives or when not to use it, such as noting that organization-wide search would use gitbook_search_organization. Still, the context is sufficiently clear for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gitbook_update_change_requestUpdate change requestAUpdate a change request's subject or status. Edits draft metadata only. GitBook REST: PATCH /spaces/{spaceId}/change-requests/{changeRequestId}.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | A new status for the change request. | |
| spaceId | Yes | The space id. | |
| subject | No | A new title/subject for the change request. | |
| changeRequestId | Yes | The change request id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation declares destructiveHint: true, and the description adds that it 'Edits draft metadata only', providing scope beyond the annotation. However, it does not disclose permissions, side effects, or response behavior, so transparency is moderate.
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 three short sentences, immediately stating the purpose, scope, and REST endpoint. Every sentence is informative and there is no redundant or promotional 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?
No output schema exists, so the description should ideally explain return values. It doesn't mention what the response contains or potential errors. The REST path and draft metadata scope are helpful, but the missing return behavior and lack of response details leave the description slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all four parameters. The description mentions 'subject or status' which aligns with schema but adds no additional semantics about allowed values or format beyond what the schema already provides. 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 tool updates a change request's subject or status, uses a specific REST endpoint, and distinguishes it from sibling create/list/get tools by focusing on the 'update' action and 'draft metadata only' 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 implies usage for updating subject or status of a change request but does not explicitly compare to alternatives like create_change_request or list_change_requests. It gives a partial constraint ('draft metadata only') but lacks explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!