Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
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 4.1/5 across 10 of 10 tools scored.
Each tool has a distinct role: document CRUD (create, get, update, archive), listing/searching, annotation create/list, and two auth helper tools. There is no overlap or ambiguity between them.
All tools follow a consistent verb_noun pattern with snake_case (e.g., create_document, list_annotations, request_device_auth). The naming is uniform and predictable across both document and auth tools.
With 10 tools, the server is well-scoped for document management plus required auth flow. It covers the essential operations without being bloated or too thin.
Core document operations are covered (create, read, update, archive, list, search), but there is no hard delete or unarchive, and annotations only support create/list (no update/delete). Additionally, there is no explicit tool for sharing documents despite the mention of shared docs.
archive_documentAInspectArchive a document. For documents you own, archives it for everyone. For shared documents, archives it only for you.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Document slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses an important behavioral trait: the effect depends on document ownership. With no annotations provided, this is valuable context. However, it does not mention reversibility, required permissions, or what happens to the document's visibility in list/search results afterward, 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 exactly two sentences, front-loaded with the action, and the second sentence clarifies a key nuance. Every word earns its place, 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?
For a simple tool with one parameter and no output schema, the description covers the core behavior and the ownership distinction, which is the most relevant contextual information. It could be more complete regarding side effects or reversal, but given the simplicity, 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?
The input schema already describes the only parameter `slug` as 'Document slug' (100% coverage). The description does not add any additional parameter-level detail, 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 'archive a document' and distinguishes it from other document tools by explaining ownership-specific behavior. This makes the tool's purpose unambiguous and differentiates it from siblings like update_document or delete (though not explicitly listed).
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 that archiving is used when a document should be removed from active use but not deleted, and it explains how the effect differs for owned vs shared documents. However, it does not explicitly state when to choose this over alternatives or mention any exclusions, so the usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_annotationAInspectAdd an annotation (comment) to a document. Pass quoted_text with the exact passage you want to annotate — the server will locate it automatically. Omit quoted_text to attach to the whole document. You can also provide start_offset + end_offset explicitly if needed.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Annotation text | |
| slug | Yes | Document slug | |
| end_offset | No | Character offset where annotation ends | |
| quoted_text | No | The exact text being annotated | |
| start_offset | No | Character offset where annotation starts |
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: the server automatically locates quoted_text, omission attaches to the whole document, and offsets can be explicitly provided. It does not cover error cases or permissions but offers meaningful behavioral context beyond a simple statement of 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?
Three sentences, front-loaded with the core purpose, followed by concise usage details. Every sentence provides useful information with no 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?
Given the tool's moderate complexity (5 params, no annotations, no output schema), the description covers the main usage modes (quoted_text, whole document, offsets). It doesn't mention return values or error behavior, but the core invocation semantics are well explained, making it sufficiently complete for an agent to select and use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the relationship between quoted_text and start_offset/end_offset, and that quoted_text is optional (can be omitted for whole-document annotation). This goes beyond the individual 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 starts with 'Add an annotation (comment) to a document,' which is a specific verb ('Add') and resource ('annotation to a document'). It clearly distinguishes from sibling tools like create_document and list_annotations, as it is the only tool for creating annotations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: pass quoted_text to annotate a specific passage, omit it to attach to the whole document, or use start_offset/end_offset explicitly. It doesn't explicitly compare to alternatives like list_annotations, but the context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_documentAInspectCreate a new mkdshare.DEV document. If visibility is omitted the document is owner-only (login_required, restricted to your email).
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Document title | |
| content | Yes | Markdown content | |
| expires_at | No | ISO 8601 datetime after which the document expires, e.g. 2026-06-01T00:00:00Z | |
| visibility | No | Who can view the document. If the user didn't specify who should see it, ask them. Omitted = owner-only (login_required, restricted to your email). | |
| editor_emails | No | Comma-separated emails that can edit this document (in addition to the owner) | |
| allowed_domain | No | Domain allowed to view, e.g. company.com (domain_restricted visibility) | |
| allowed_emails | No | Comma-separated emails allowed to view (login_required visibility) | |
| domain_can_edit | No | When true, all users in allowed_domain can edit (not just view) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It discloses a key behavioral default: if visibility is omitted, the document is owner-only (login_required, restricted to your email). This is a meaningful security-relevant behavior beyond the schema. It does not cover authentication or success response, but the disclosed default is significant.
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, approximately 30 words, with the primary purpose front-loaded in the first sentence and the crucial default detail in the second. It is concise, free of filler, and every word adds value.
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?
Despite the absence of an output schema and the presence of eight parameters, the schema descriptions are very thorough, covering all parameters with examples. The description adds the key default visibility behavior, which is the most important contextual nuance. It does not mention prerequisites or response format, but overall it is adequate for a create operation given the rich schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter meaning beyond the schema; it repeats the visibility default that is already fully documented in the parameter description. All eight parameters are thoroughly described in the schema, so the description does not need to compensate.
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 operation: 'Create a new mkdshare.DEV document.' The verb 'Create' and resource 'document' precisely define the purpose, and it is distinct from siblings like update_document. The additional sentence about visibility default adds purposeful nuance without confusing the primary action.
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 by mentioning the default visibility behavior when omitted, which is an important usage decision. However, it does not explicitly contrast with alternatives (e.g., update_document for editing) or state when not to use this tool. Still, the creation context is obvious and unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_documentAInspectRead the full markdown content of a document by its slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | 8-character document slug from the URL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral disclosure burden. The verb 'Read' clearly indicates a non-destructive operation, and 'full markdown content' describes the return value, but no additional details about errors, rate limits, or authentication are given.
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, front-loaded with the verb 'Read', and contains no filler or repetition. Every word contributes to specifying the operation.
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 fully documented parameter and no output schema, the description fully specifies the input (slug), the operation (read), and the return value (full markdown content). It is self-sufficient and leaves no major ambiguity.
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 for the single parameter 'slug', including its 8-character format, so the description need not add further details. The phrase 'by its slug' merely references the parameter without extending its 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 the specific verb 'Read' with resource 'document' and explicitly mentions 'full markdown content' and 'by its slug', distinguishing it from sibling tools that create, update, archive, list, or search documents.
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 have a slug and need the full content of a specific document—but does not explicitly compare against alternatives like list_documents or search_documents. It provides no exclusion criteria or conditional guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_annotationsAInspectList all annotations (comments) on a document.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Document slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden. 'List' implies a read-only operation, but the description doesn't disclose potential pagination, ordering, or authorization requirements. It adds minimal context beyond the operation itself, though for a simple list this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise, front-loaded, and contains no wasted words. It states the action and scope efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no nested objects, no output schema), the description is sufficiently complete for an agent to select and invoke the tool. It does not describe the return format, but that is not strictly necessary for a simple list operation without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for 'slug' is 'Document slug', which covers the parameter's meaning 100%. The tool description reinforces that the slug identifies the document but adds no additional syntax or format details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('annotations'), and the scope ('on a document'). This distinguishes it from siblings like create_annotation (which creates) and list_documents (which lists documents).
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 clearly implies when to use this tool: to retrieve all annotations for a specific document. Though it doesn't explicitly mention alternatives, the context is unambiguous and no exclusions are needed for such a simple operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_documentsAInspectList all mkdshare.DEV documents owned by or shared with the authenticated user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It clearly conveys the read-only nature (listing) and the scope of results, but it omits details about pagination, ordering, or result format. This is adequate 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?
The description is a single, front-loaded sentence that conveys the core action and scope without any filler. Every word is informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema) and its clear scope, the description is largely complete. It could optionally mention the return type, but for a list operation the agent can reasonably infer a list of documents is returned.
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 schema coverage is 100% (vacuously). The description rightly does not attempt to explain parameters, and the baseline for 0-parameter tools is 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 verb 'List' and the resource 'mkdshare.DEV documents', with a specific scope ('owned by or shared with the authenticated user'). This distinguishes it from siblings like search_documents and get_document.
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 search_documents or get_document. It implies a broad listing but does not mention any exclusions or specific contexts where another tool would be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
poll_device_authAInspectCheck whether the user has approved the device authorization. Call every 5 seconds (or the interval returned by a slow_down response) until status is 'complete'. Save the returned api_token to your MCP server config.
| Name | Required | Description | Default |
|---|---|---|---|
| device_code | Yes | device_code returned by request_device_auth |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well. It discloses the polling behavior, handling of slow_down responses, and the terminal condition ('complete'). It also mentions the api_token return, which helps the agent understand the tool's practical 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 two concise sentences that deliver essential information without waste. It front-loads the purpose and follows with actionable usage details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter polling tool, the description fully covers the usage loop, termination condition, and output handling. No output schema exists, but the description indicates what to do with the response (save api_token). This is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the parameter (device_code returned by request_device_auth) with 100% coverage. The description does not add additional parameter-specific semantics, 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 tool's purpose: to check whether the user has approved device authorization. It uses a specific verb ('check') and resource ('device authorization'), which distinguishes it from sibling tools like request_device_auth that initiates the flow.
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 explicit usage instructions: call every 5 seconds or the interval from a slow_down response until status is 'complete'. It also specifies what to do with the returned api_token (save to config), making the polling workflow clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
request_device_authAInspectStart a headless Google sign-in. Call this FIRST if you don't have an API token yet. Returns a user_code and verification_url for the user to visit, plus a device_code to use with poll_device_auth. No Bearer token required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on full responsibility. It discloses that no Bearer token is required and details the exact returned values (user_code, verification_url, device_code), offering enough behavioral transparency for an agent. It stops short of 5 by omitting any error/expiration details, but these are not critical for this simple auth step.
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 sentences, each earning its place: purpose, trigger condition, and output usage. It is front-loaded with the action and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 0-parameter tool with no output schema, the description fully covers what it does, when to call it, and how to proceed with the returned codes. The explicit link to poll_device_auth ensures the agent understands the overall flow, making this complete 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 tool has zero parameters, so a baseline of 4 is appropriate. The description adds no parameter information, but none is needed since the schema is empty and the description clarifies the context in which the tool is invoked.
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 ('Start a headless Google sign-in.') and differentiates it from siblings by explicitly referencing poll_device_auth as the next step, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance ('Call this FIRST if you don't have an API token yet') and directs the use of the returned device_code with poll_device_auth, giving clear context relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_documentsAInspectSearch mkdshare.DEV documents by title and content. Returns documents owned by or shared with the authenticated user that match the query.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search string matched case-insensitively against document title and content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It discloses the important scoping rule (only documents owned by or shared with the authenticated user are returned) and the search action itself, but does not mention whether results are paginated, sorted, or limited, nor does it explicitly confirm read-only 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 two sentences, front-loaded with the core action and scope. Every word is useful, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema), and the description explains the search scope and result set. However, it does not specify the result format (e.g., list of document summaries vs full objects) or any limits, which are relevant given the absence of an output schema and 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 covers 100% of the single parameter with a clear description (case-insensitive match against title and content). The tool description only repeats this information ('by title and content') without adding new meaning, 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 searches documents by title and content, with an explicit resource (mkdshare.DEV documents) and scope (owned or shared with user). This distinguishes it from sibling tools like list_documents (which lists without searching) and get_document (which retrieves a specific document).
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 finding documents by keyword, but does not explicitly state when to use this over list_documents or get_document. It provides no exclusions or alternative tool mentions, leaving the agent to infer from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_documentAInspectUpdate an existing document you own. Omit any field to keep its current value.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Document slug | |
| title | No | New title | |
| content | No | New markdown content | |
| expires_at | No | ISO 8601 expiry datetime; omit to keep current | |
| visibility | No | New visibility level | |
| editor_emails | No | Comma-separated emails that can edit; pass empty string to clear | |
| allowed_domain | No | Domain allowed to view, e.g. company.com; required for domain_restricted | |
| allowed_emails | No | Comma-separated emails allowed to view; pass empty string to clear | |
| domain_can_edit | No | When true, all users in allowed_domain can edit (not just view) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the disclosure burden. It discloses two important behaviors: ownership is a precondition, and omitted fields retain their current values (partial update). However, it does not disclose expected return value, error behavior, or potential side effects, which is a significant gap 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 two short sentences, front-loaded with the core action, and every phrase adds value. It avoids restating the schema or including 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?
Given the tool has 9 parameters, no output schema, and no annotations, the description is minimal but covers the key behavioral rule (omit to keep). However, it fails to mention what the tool returns after a successful update, and does not clarify edge cases such as interactions between visibility and allowed_domain, or whether updating an archived document is allowed. The rich schema compensates for some, but not all, missing 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 already describes each parameter in full (100% coverage), so the baseline is 3. The description adds valuable cross-parameter semantics: 'Omit any field to keep its current value' clarifies that all fields except slug are optional and that partial updates are supported. This goes beyond what the schema says individually.
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 ('Update') and resource ('existing document') and adds an important ownership qualifier ('you own'). This clearly distinguishes it from sibling tools like create_document, get_document, and archive_document.
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 'you own' gives clear context for when to use the tool, but it does not explicitly mention alternatives or when not to use it (e.g., archived documents). There is no guidance on sibling tools like archive_document or create_document, so usage is 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.
upload_imageAInspectUpload an image (png, jpeg, gif, webp; max 1MB) for embedding in documents. Returns a URL and a ready-to-paste markdown snippet. Images are served at an unguessable URL — anyone with the exact link can view.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Base64-encoded image bytes (standard alphabet, no data: URI prefix) | |
| filename | Yes | Original filename, e.g. screenshot.png |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavior disclosure. It discloses file format restrictions, size limit, return value (URL and markdown snippet), and a security caveat (unguessable URL, anyone with link can view). This is solid but omits error handling or permission requirements.
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 primary purpose and then providing key constraints and return info. No fluff or redundant statements; every sentence contributes value.
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 tool with no output schema and no annotations, the description covers input formats/size, return value, and security implications. While it lacks edge-case details (e.g., what happens if size exceeded), it provides sufficient context for an agent to use 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 input schema provides 100% coverage for both parameters (`data` and `filename`) with detailed descriptions. The tool description does not add additional parameter-level semantics beyond what the schema already states, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Upload an image (png, jpeg, gif, webp; max 1MB) for embedding in documents.' It uses a specific verb (Upload), identifies the resource (image), and implies its role in creating/updating documents, distinguishing it from sibling tools like create_document or update_document.
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 'for embedding in documents' provides a clear intended use case. It doesn't explicitly mention alternatives or exclusions, but the sibling tools are document-management focused, making it obvious this tool is for image uploads. This is sufficient guidance for 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.
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!
