Moxie Docs
Server Details
Repos indexed with Moxie Docs can use our MCP to let agents fetch codebase conventions, find affected docs from changes, pull outdated docs to update, and identify orphaned docs to keep up to date. Let your agents keep your documentation accurate and updated at all times.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
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.
Tool Definition Quality
Average 4.6/5 across 10 of 10 tools scored.
Each tool has a clearly distinct purpose: context, conventions, gaps, impact, opportunities, patterns, listing, removal, update, and search. Even similar tools like get_doc_gaps and get_documentation_opportunities are differentiated by superset vs subset, and descriptions clarify when to use each.
All tools follow a consistent verb_noun pattern in snake_case (get_X, list_X, propose_X, search_X). The verbs are semantically appropriate for the action (get for retrieval, propose for write, list for enumeration, search for query).
With 10 tools, the server is well-scoped for a documentation management domain. Each tool serves a distinct function without redundancy, covering reading, writing, and searching. The count feels neither too sparse nor overwhelming.
The tool surface covers the full documentation lifecycle: reading context, conventions, patterns, gaps, and opportunities; proposing updates and removals; listing and searching. The server enables agents to understand, plan, and execute documentation changes within the same PR, with no obvious missing operations.
Available Tools
10 toolsmoxie.get_ai_contextARead-onlyIdempotentInspect
Get the compact briefing an agent should read before editing this repository: index status, verified commands, agent tips, top conventions, open documentation gaps, and queued documentation opportunities. Read-only; no side effects. Returns a single Markdown document. Call this first at the start of a task; once you know which files you'll change, follow up with get_doc_impact for path-scoped guidance.
| Name | Required | Description | Default |
|---|---|---|---|
| repository | No | The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. The description reinforces 'Read-only; no side effects' and adds that it returns a single Markdown document. It also explains behavior when the repository parameter is omitted (returns list). This goes beyond annotations, though redundant on read-only.
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, each purposeful and front-loaded. First sentence states what is returned. Second declares read-only nature. Third provides usage order. 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 simplicity (one optional parameter, no output schema, clear annotations), the description covers expected behavior, return format, usage order, and parameter semantics. No gaps for an agent to misinterpret.
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 for the single parameter. The description adds practical advice ('Always pass this unless your token is scoped to a single repository') and explains the fallback response when omitted, adding value beyond the schema 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 tool retrieves a compact briefing for agents before editing a repository, listing specific contents (index status, commands, tips, conventions, gaps, opportunities). It distinguishes from siblings by noting to use get_doc_impact afterward for path-scoped guidance.
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?
Explicitly instructs to call this tool first at task start and to follow up with get_doc_impact when files are known. Also explains when to pass the repository parameter versus when it is optional, providing concrete usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
moxie.get_conventionsARead-onlyIdempotentInspect
Get the coding conventions Moxie inferred for the repository. Read-only; no side effects. Returns a Markdown list grouped by category (e.g. testing, structure, docs, review); each convention has a title, summary, confidence score, agent guidance, and the source file paths that evidence it. Use this for the general rules to follow; when you already know the files you're about to edit, prefer moxie.get_doc_impact for conventions scoped to those paths.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Optional category filter, such as testing, structure, docs, or review. | |
| repository | No | The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description states 'Read-only; no side effects' which aligns with annotations. Adds detail about return format (Markdown list grouped by category, each with title, summary, confidence, agent guidance, source files) that annotations do not provide.
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?
Description is concise at a few sentences, front-loaded with core function, then behavior, return format, and usage guidance. Every sentence adds value with no wasted words.
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 (2 optional params, no output schema), the description covers purpose, behavior, return format, and usage alternatives. With annotations confirming read-only and idempotent, it is complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for both parameters. The tool description does not add additional meaning beyond what the schema already provides for the parameters, 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?
Clearly states 'Get the coding conventions Moxie inferred for the repository' with specific verb-resource pairing. Differentiates from sibling tool moxie.get_doc_impact by specifying when to prefer that alternative.
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?
Explicitly says 'Use this for the general rules to follow; when you already know the files you're about to edit, prefer moxie.get_doc_impact for conventions scoped to those paths.' Provides clear context for when to use and when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
moxie.get_doc_gapsARead-onlyIdempotentInspect
List the unresolved documentation gaps Moxie found — areas of the codebase that lack docs. Read-only; no side effects. Returns a Markdown list, each gap with a title, severity, summary, and suggested file paths. This is gaps only; for the full prioritized work queue that also includes drift repairs and PR-template work, use get_documentation_opportunities, and to scope gaps to files you're about to edit use get_doc_impact.
| Name | Required | Description | Default |
|---|---|---|---|
| severity | No | Optional severity filter: high, medium, low, or info. | |
| repository | No | The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description reinforces 'Read-only; no side effects' and adds return format details (Markdown list with title, severity, etc.), which adds value 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?
Four sentences with zero waste. Front-loaded with purpose, followed by behavior, return format, and sibling differentiation. Every 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 simplicity (no output schema, two simple params), the description fully covers what the tool does, when to use it, what it returns, and how it differs from siblings. No gaps remain.
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. Description does not add extra meaning beyond what the schema provides, meeting the baseline of 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?
Clearly states the verb ('List') and resource ('unresolved documentation gaps'), immediately distinguishing it from sibling tools like get_documentation_opportunities and get_doc_impact in the next sentence.
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?
Explicitly explains when to use this tool versus alternatives: 'for the full prioritized work queue... use get_documentation_opportunities, and to scope gaps to files you're about to edit use get_doc_impact.' Also notes it's read-only and returns gaps only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
moxie.get_doc_impactARead-onlyIdempotentInspect
Given the file paths an agent is about to change (and optionally a subset being deleted), return the conventions, documentation gaps, and existing/related docs whose evidence overlaps those paths, plus a net-new/undocumented analysis and any removal candidates. Read-only; no side effects. Returns a Markdown report. Call this BEFORE writing code so doc updates land in the same PR; then use propose_doc_update to write a doc, or propose_doc_removal for an orphaned one.
| Name | Required | Description | Default |
|---|---|---|---|
| repository | No | The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer. | |
| changedPaths | Yes | Repository-relative file paths the agent intends to modify (e.g., apps/web/src/app/api/billing/webhook/route.ts). | |
| deletedPaths | No | Subset of paths that are being DELETED. Moxie flags any doc whose every cited source path is in this list as a removal candidate for moxie.propose_doc_removal. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description reinforces read-only with no side effects and adds that it returns a Markdown report with specific content. No contradictions; the description adds 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?
The description is concise yet comprehensive. It is front-loaded with core functionality, then usage guidelines. Every sentence adds value, and there is no redundancy. The structure is logical and efficient.
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 output schema, the description fully explains the return value (Markdown report with conventions, gaps, etc.). It covers the role of each parameter, when to use the tool, and how to proceed afterwards. Complete for a tool of this 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?
Schema coverage is 100%, so baseline is 3. The description does not add substantial meaning beyond the schema for parameters; it only mentions 'file paths' and 'subset being deleted' which mirror the schema descriptions. No extra parameter details are provided.
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 specifies that the tool analyzes documentation impact of file changes, returning conventions, gaps, related docs, net-new analysis, and removal candidates. It explicitly distinguishes from sibling tools by stating when to use this tool and then proceed with propose_doc_update or propose_doc_removal.
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 guidance: call BEFORE writing code so doc updates land in the same PR, then use propose_doc_update to write a doc or propose_doc_removal for an orphaned one. It also implies it is read-only and not for writing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
moxie.get_documentation_opportunitiesARead-onlyIdempotentInspect
List the actionable documentation updates Moxie recommends as a prioritized queue: missing docs, drift repairs, and PR-template work. Read-only; no side effects. Returns a Markdown list, each opportunity with a title, kind (documentation_gap | documentation_drift | pr_template), severity, summary, suggested action, estimated files changed, and source paths. Use this to pick the next doc task; it is the superset of get_doc_gaps (which lists gaps only).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional kind filter: documentation_gap, documentation_drift, or pr_template. | |
| severity | No | Optional severity filter: high, medium, low, or info. | |
| repository | No | The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint; description adds 'Read-only; no side effects,' return format details, and edge-case behavior for repository filter. Provides useful 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?
Three sentences: purpose, behavior/format, usage guidance. Front-loaded and efficient 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?
No output schema, but description details return format (Markdown list with fields). Addresses repository edge case. Lacks error handling or limits, but adequate for a list 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?
Schema coverage is 100% (baseline 3). Description adds meaning: explains repository behavior when omitted, lists possible kind and severity values explicitly, and notes case-insensitivity.
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?
Clearly states it 'List the actionable documentation updates Moxie recommends,' specifying verb, resource, and scope. Differentiates from sibling get_doc_gaps by calling itself the superset.
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?
Explicitly directs 'Use this to pick the next doc task' and contrasts with sibling: 'it is the superset of get_doc_gaps (which lists gaps only).'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
moxie.get_documentation_patternsARead-onlyIdempotentInspect
Get Moxie's summary of how THIS repository organizes and maintains documentation — where docs live relative to code and how they are kept current. Read-only; no side effects. Returns a Markdown list of pattern entries, each with a title, explanation, and source citations. Use this to decide WHERE a new doc should go before calling propose_doc_update; for the list of WHICH docs need work, use get_documentation_opportunities instead.
| Name | Required | Description | Default |
|---|---|---|---|
| repository | No | The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description states 'Read-only; no side effects,' which matches annotations (readOnlyHint, idempotentHint, destructiveHint). It adds value by describing the return format and usage context, though annotations already cover safety traits.
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 well-structured sentences: first states purpose, second describes output and safety, third provides usage guidance and sibling differentiation. No unnecessary words.
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 description fully explains what the tool returns and when to use it. It does not detail error cases or behavior when repository is omitted (but schema covers that). For a simple read tool, this is sufficient.
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 the 'repository' parameter. The description does not add additional meaning 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 tool retrieves a summary of documentation patterns for a repository, specifying the output format (Markdown list) and distinguishing it from the sibling tool get_documentation_opportunities by contrasting 'WHERE' vs 'WHICH'.
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?
Explicitly tells when to use this tool (to decide where a new doc should go) and provides an alternative (get_documentation_opportunities for which docs need work), along with a prerequisite call (propose_doc_update).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
moxie.list_docsARead-onlyIdempotentInspect
List the repository's generated documentation as a browsable table of contents — every doc page, not a query-filtered subset. Read-only; no side effects. Returns Markdown grouped by section, each entry with its title, slug, repository path, and source paths, plus the total count and a pagination cursor so you can tell whether more pages remain (no silent truncation). Use this to see what docs already exist before adding one (so you don't duplicate) or to find the slug to pass to propose_doc_update; when you are hunting for a specific topic, search_docs is more direct.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum docs to return (1-200, default 50). | |
| offset | No | Number of docs to skip for pagination (default 0). Use the cursor in the response to fetch the next page. | |
| section | No | Optional section/collection filter (case-insensitive substring), e.g. "Backend" or "Billing". Omit to list every section. | |
| repository | No | The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral details: returns Markdown grouped by section, includes title, slug, repository path, source paths, total count, and a pagination cursor, and explicitly states 'no silent truncation'. No contradiction with 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 well-structured sentences. First sentence front-loads purpose and outcome. Second sentence adds context and usage guidance. No extraneous words; every phrase 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?
Despite having no output schema, the description covers return structure (grouped Markdown with fields), pagination (cursor, no silent truncation), and explicit use cases. Four parameters are all optional with clear roles. For a listing tool, the description is fully 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 coverage is 100%, baseline 3. Description adds meaningful context beyond schema: explains the repository parameter's behavior ('Always pass this unless your token is scoped to a single repository' and consequence of omission) and clarifies the section filter as case-insensitive substring. This extra guidance 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 tool lists 'the repository's generated documentation' as a 'browsable table of contents' and specifies it returns 'every doc page, not a query-filtered subset'. It distinguishes from sibling search_docs by noting when to use that alternative.
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?
Explicit guidance: 'Use this to see what docs already exist before adding one (so you don't duplicate) or to find the slug to pass to propose_doc_update; when you are hunting for a specific topic, search_docs is more direct.' This gives clear when-to-use and when-not-to-use, naming the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
moxie.propose_doc_removalAInspect
Propose deleting a Moxie-tracked documentation file that your change makes irrelevant, as part of YOUR current change. Moxie validates the path and returns it for you to delete in your working branch; Moxie itself does not delete files or open a PR — the deletion happens in your branch, so it lands in the SAME PR as the code. Returns the resolved path to delete. Provide either slug or targetPath.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Slug of the existing generated doc to remove. | |
| reason | No | Why this doc is no longer relevant. | |
| repository | No | The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer. | |
| targetPath | No | Repository-relative path of the doc to remove (must be a Moxie-tracked doc). Use instead of slug. | |
| removedSourcePaths | No | Code paths being deleted that made this doc irrelevant, for provenance. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that Moxie returns a path to delete but does not perform deletion, aligning with destructiveHint=false. Adds context about the deletion happening in the user's branch, which is beyond the 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?
Four sentences efficiently covering purpose, workflow, return value, and parameter usage. Front-loaded with the most critical information, no wasted words.
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 (5 parameters, no output schema), the description adequately explains the workflow and return value. Could mention error handling for missing parameters, but sufficient for basic 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?
With 100% schema coverage, the description adds value by clarifying the mutual exclusivity of slug and targetPath and stating the return value. This goes beyond the schema's per-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 verb 'Propose deleting' and the resource 'Moxie-tracked documentation file' with context 'as part of YOUR current change'. It distinguishes from siblings like propose_doc_update by specifying removal.
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?
Explicitly explains when to use (when a doc is made irrelevant) and what Moxie does not do (does not delete files or open a PR), guiding the agent on workflow. Lacks direct comparison to propose_doc_update but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
moxie.propose_doc_updateAInspect
Propose a documentation file to add or update as part of YOUR current change. Records a new proposal each call (not idempotent) and does NOT modify your repository or open a PR — Moxie resolves the target path and returns the path + Markdown for YOU to write into your working branch, so the docs land in the SAME PR as the code. Returns the resolved target path and the content to write. Provide either targetPath or baseSlug.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Short human title for the documentation update. | |
| reason | No | Why this doc is being added or changed. | |
| baseSlug | No | Slug of an existing generated doc to update instead of supplying targetPath. | |
| markdown | Yes | The documentation content (Markdown) to write to the target file. | |
| repository | No | The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer. | |
| targetPath | No | Repository-relative path to write the doc to (e.g., docs/billing.md). Omit to resolve from baseSlug. | |
| sourcePaths | No | Code paths this doc documents, for provenance. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-readonly, non-destructive, non-idempotent. The description explicitly states the tool is not idempotent and does not modify repo or open PR, which matches annotations. It adds context that each call records a new proposal and returns path+content for the agent to write.
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 dense paragraph that front-loads key information. It could be more structured (e.g., bullet points) but every sentence adds value. No wasted words.
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 7 parameters and no output schema, the description covers purpose, non-idempotency, non-modification, mutual exclusion of targetPath/baseSlug, and basic return value. It is sufficiently complete for an agent to understand and use the tool 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?
With 100% schema coverage, baseline is 3. The description adds mutual exclusion guidance for targetPath and baseSlug, and clarifies the return value. It also explains when to omit repository parameter. This adds meaning beyond the schema.
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 proposes a doc to add or update as part of the current change, distinguishing it from sibling tools like propose_doc_removal or search_docs. It specifies the verb 'propose' and the resource 'documentation file', and adds that each call records a new proposal.
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 explains when to use this tool (for adding/updating docs as part of the current change) and what it does not do (modify repo or open PR). It also advises to provide either targetPath or baseSlug. However, it does not explicitly compare with alternatives or exclude scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
moxie.search_docsARead-onlyIdempotentInspect
Keyword and semantic search across the connected repository's generated docs, conventions, documentation gaps, AI-context notes, and indexed code. Read-only; no side effects. Returns ranked matches in Markdown grouped into Documentation and Code sections, each with a title, snippet, and source paths. Use for open-ended lookups when you don't know which category holds the answer; when you do, the specific getters (get_conventions, get_doc_gaps, get_documentation_opportunities) are more direct. Omitting query returns recent context instead.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum matches to return (1-20, default 8). | |
| query | No | Search phrase or topic. Omit to return recent context for the repository. | |
| repository | No | The target repository as "owner/name" (e.g. "acme/app"). Always pass this unless your token is scoped to a single repository. Matching is case-insensitive. If omitted when the token serves multiple repos, the call returns the list of repositories to choose from instead of an answer. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that the tool is 'Read-only; no side effects' (consistent with annotations) and describes the return format: 'Returns ranked matches in Markdown grouped into Documentation and Code sections, each with a title, snippet, and source paths.' No contradictions.
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 concise (four sentences) and front-loaded with purpose. Every sentence adds value: purpose, read-only nature, return format, usage guidance, parameter nuances. No redundant or missing 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?
Given no output schema, the description adequately explains the return format and groups. It covers all three parameters with their behaviors. The tool's complexity is moderate, and the description 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?
Schema coverage is 100%, so baseline is 3. The description adds meaningful behavior: for 'query', it notes 'Omit to return recent context for the repository'; for 'repository', it explains the behavior when omitted (returns list of repos if token serves multiple repos). These details go beyond the schema 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 tool's purpose: 'Keyword and semantic search across the connected repository's generated docs, conventions, documentation gaps, AI-context notes, and indexed code.' It specifies the verb (search) and the resource (repository documents), and distinguishes from sibling tools by noting that specific getters are more direct when the category is known.
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 explicitly provides usage guidance: 'Use for open-ended lookups when you don't know which category holds the answer; when you do, the specific getters (get_conventions, get_doc_gaps, get_documentation_opportunities) are more direct.' This tells the agent when to use this tool and when to use alternatives.
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.
Discussions
No comments yet. Be the first to start the discussion!