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.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description redundantly states 'Read-only; no side effects' but adds value by disclosing the return format ('Returns a single Markdown document') and the fallback behavior when the token serves multiple repos. 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 brief but packed with essential information: purpose, content list, safety, return type, and usage order. It is front-loaded with the core action and structured logically, with zero 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 simple parameter set (1 optional param), rich annotations, and no output schema, the description covers everything an agent needs: what it does, when to use it, what it returns, and how to handle the edge case of omitted repository. It is fully complete for its 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 description coverage is 100% and the property description fully explains the repository parameter, including case-insensitivity and the multi-repo fallback. The tool description repeats this information but does not add any new semantics beyond what the schema already provides, 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: it returns a compact briefing for pre-edit context, listing specific content (index status, commands, tips, etc.). It differentiates from siblings like get_conventions and get_doc_gaps by being a combined briefing, and it explicitly mentions get_doc_impact as a follow-up, showing awareness of sibling tools.
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 gives explicit usage direction: 'Call this first at the start of a task' and instructs to follow up with get_doc_impact for path-scoped guidance. This provides clear when-to-use and an alternative, exceeding baseline expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Given file paths an agent is about to touch, return structured context for any API endpoints they map to: method, path, request/response schema, and known consumers/features. Read-only; no side effects. Call this before editing API route or schema code, alongside get_doc_impact.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | No | Repository-relative file paths to inspect for API endpoint context. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value by declaring no side effects and outlining the structured return content (method, path, request/response schema, known consumers/features), which is not fully available from any output schema.
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 well-structured sentences: purpose, side-effect declaration, and usage timing. It is front-loaded with the most important information and contains no filler or redundant restating.
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 two-parameter, no-output-schema tool, the description covers the return payload, read-only nature, and when to invoke it. It could be slightly stronger by explaining fallback behavior when repository is omitted, but the schema already covers that, so the overall context 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 description coverage is 100%, so the baseline is 3; the schema already explains paths and repository semantics thoroughly, including multi-repo behavior. The description adds little beyond framing paths as files 'an agent is about to touch,' so no extra score is warranted.
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 ('return structured context') tied to a clear resource ('API endpoints') derived from file paths. It enumerates the returned fields (method, path, request/response schema, consumers/features) and distinguishes this from sibling tools by pairing it with get_doc_impact.
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 says to call this tool before editing API route or schema code, and names get_doc_impact as a complementary tool. It does not provide a formal when-not-to-use exclusion, but the use case is clearly scoped to pre-edit API impact assessment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral detail beyond annotations by describing the Markdown return format, grouping by category, and the fields included for each convention. It does not contradict annotations and adds context that an agent needs to interpret results.
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 compact and front-loaded: purpose, side-effect safety, output format, and usage guidance appear in four tight sentences with no filler. Each sentence earns its place and the alternative-tool pointer is included without bloat.
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 has only two optional parameters, no output schema, and safe read-only annotations. The description compensates for the missing output schema by detailing the returned Markdown structure and fields. The repository-omission behavior is captured in the schema, so no critical context is missing for an agent to invoke this 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?
Schema description coverage is 100%, and both parameters have clear descriptions including examples, case-insensitivity, and behavior when omitted. The main description does not add parameter-level detail, but the schema already carries the full burden, 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 starts with a specific verb and resource ('Get the coding conventions Moxie inferred for the repository') and clearly defines the output format and categories. It also explicitly distinguishes itself from moxie.get_doc_impact by noting the scope difference, which makes 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 gives explicit when-to-use guidance ('Use this for the general rules to follow') and an explicit alternative with a condition ('when you already know the files you're about to edit, prefer moxie.get_doc_impact'). This is strong usage direction that helps an agent choose correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value beyond that by specifying the return shape: a Markdown list with each gap's title, severity, summary, and suggested file paths. It does not go into pagination or the fallback repository-selection behavior, but that is covered by the schema.
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 earning its place: the first states the tool's purpose, the second describes the return value, and the third names the correct alternatives. No repetition of schema or annotation data.
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 has few parameters and no output schema, so the description's explanation of the Markdown output is sufficient. It also provides sibling differentiation and confirms no side effects, making a complete decision picture for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented. The tool description does not add new parameter-level semantics beyond mentioning severity in the output summary, 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 opens with a specific verb-resource pair: "List the unresolved documentation gaps Moxie found - areas of the codebase that lack docs." It also distinguishes itself from the closest siblings by stating "This is gaps only" and naming get_documentation_opportunities and get_doc_impact as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use the tool versus alternatives: use get_documentation_opportunities for the full prioritized work queue and get_doc_impact to scope gaps to files being edited. This is an explicit when/when-not statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly states 'Read-only; no side effects.' It adds context about the return format (Markdown report) and the behavior for deletedPaths (flags removal candidates), which goes beyond annotations. While the description aligns with annotations, it could mention rate limits or auth requirements, but for a read-only analysis tool, this is quite thorough. 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?
The description is two sentences, front-loaded with the core purpose and follow-up actions. No waste; every clause adds value — the timing guidance, read-only assurance, and linkage to sibling tools. Excellent structure with clear flow.
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 complex with 3 params and no output schema, but the description covers the purpose, usage timing, and follow-ups. It explains the specific outputs (conventions, gaps, removal candidates) and the return format. It could optionally mention what to do if paths don't overlap anything, but overall it's complete enough given the schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters in detail. The description adds context about how deletedPaths influence removal candidate flags and the repository omission behavior (returns list of repos), but these are already in the schema. The description doesn't add significant new meaning 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?
The description clearly states the tool's purpose: given file paths about to change, it returns conventions, documentation gaps, and related docs with overlapping evidence, plus a net-new analysis and removal candidates. It distinguishes itself from siblings by focusing on impact analysis before code changes, explicitly naming propose_doc_update and propose_doc_removal as follow-ups, making the purpose specific and non-ambiguous.
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 it BEFORE writing code so doc updates land in the same PR, and then use propose_doc_update or propose_doc_removal for follow-ups. It also implicitly sets when not to use it (i.e., after code changes), which helps the agent choose between this and other moxie tools like search_docs or list_docs for different needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces this with 'Read-only; no side effects.' It goes beyond annotations by describing the return format (Markdown list) and the content fields of each opportunity. This provides useful behavioral context without contradicting 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?
The description is compact and well-structured: purpose, side-effect note, output format, and usage guidance in four sentences. Every sentence adds value, and there is no redundant or filler 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?
Since there is no output schema, the description properly compensates by detailing the return format and item fields. Combined with schema-covered parameters and sibling comparison, the agent receives enough context to select and invoke 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?
Schema description coverage is 100%, so the schema already documents kind, severity, and repository well. The description adds little parameter-level meaning beyond restating the kind values and implying filtering through the output categories; the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing actionable, prioritized documentation updates (missing docs, drift repairs, PR-template work). It is explicitly contrasted with get_doc_gaps as the superset, so it is easy for an agent to distinguish among siblings.
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 gives explicit usage guidance: 'Use this to pick the next doc task.' It also explains how it relates to the specific alternative get_doc_gaps ('it is the superset... which lists gaps only'), helping the agent choose between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces with 'Read-only; no side effects.' It also adds useful behavioral detail about the output format (Markdown list with title, explanation, source citations). The description is consistent with annotations and adds context about return shape and usage context. Though it could mention pagination or rate limits, but those are not expected here. This is above baseline since it adds value 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?
Three sentences, each purposeful: what it does, output format, and usage guidance. No fluff, front-loaded with the core purpose, then output detail, then usage guidance. 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?
For a simple read-only tool with one optional parameter and no output schema, the description covers the purpose, output format, usage context, and distinguishes from siblings. Combined with rich annotations (readOnly, idempotent, non-destructive), it leaves no gaps. The description also explains the fallback behavior of the parameter when omitted, which is helpful for multi-repo tokens.
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 single parameter `repository` is fully documented in the schema (100% coverage) with format, case-insensitivity, and fallback behavior when omitted for multi-repo tokens. The description adds the purpose of the parameter contextually (decision-making about docs), but the schema already covers semantics. Since coverage is 100%, baseline is 3, and the description slightly enhances by tying the parameter to the tool's purpose, so 4 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 returns a summary of how the repository organizes and maintains documentation, with a specific output format (Markdown list with title, explanation, source citations). It also distinguishes itself from siblings by naming get_documentation_opportunities as the alternative for knowing which docs need work.
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 states when to use this tool (to decide WHERE a new doc should go) and when not to, pointing to get_documentation_opportunities for the list of which docs need work, and propose_doc_update as the subsequent step. This provides clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring read-only, idempotent, non-destructive, the description adds beyond them: it discloses the return format (Markdown grouped by section), fields included (title, slug, repository path, source paths), total count and pagination cursor, and explicitly promises no silent truncation. This is rich, annotation-complementing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then safety, then return details, then usage guidance. It is three sentences, each earning its place, no fluff or repetition of schema field names that are already self-explanatory.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 optional params, rich annotations, and no output schema, the description covers the key operational behaviors: read-only guarantee, return structure, pagination honesty, repository fallback behavior, and when to use it versus siblings. It is complete for an agent to decide whether and how to call it.
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 contextual meaning beyond the schema: it explains the repository fallback behavior (returns repository list when omitted with multi-repo tokens) and mentions the cursor in the response for pagination. It doesn't elaborate on section filter syntax beyond what the schema gives, but the added behavior notes justify 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 states a specific verb ('List') and resource ('repository's generated documentation'), and explicitly contrasts with a 'query-filtered subset' and sibling tool search_docs. It distinguishes itself from siblings by positioning itself as a full table of contents.
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 gives explicit when-to-use guidance: use before adding a doc to avoid duplication, and to find slugs for propose_doc_update. It also states that search_docs is more direct for topic hunting, naming the alternative explicitly. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide little (readOnlyHint=false, destructiveHint=false), so the description carries the explanatory burden. It clearly explains that Moxie only validates and returns the path, does not delete files or open a PR, and that the actual deletion occurs in the user's branch. This is valuable, non-obvious behavioral context 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?
The description is three sentences long, front-loaded with the core purpose, and each sentence adds meaningful information: what the tool does, the division of responsibility between Moxie and the user, and the return value. No wasted words or repetition.
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 tells the agent the output (resolved path), the workflow (delete in your branch), and the parameter choice (slug or targetPath). It does not describe error behavior or edge cases like invalid paths or multi-repository handling, but the schema already documents the repository caveat. For a moderate-complexity tool with no output schema, this is sufficient, though not exhaustive.
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 important semantic guidance: 'Provide either slug or targetPath', clarifying that these are alternative ways to identify the doc, which is not encoded as an official oneOf constraint in the schema. This goes beyond the schema's existing field 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 uses a specific verb ('Propose deleting') and a clear resource ('Moxie-tracked documentation file'), and immediately clarifies that Moxie itself does not delete files or open a PR. This distinguishes it from sibling tools like propose_doc_update, list_docs, and get_doc_impact, 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 gives clear context for when to use the tool: when a change makes an existing doc irrelevant, and the deletion should land in the same PR. It does not explicitly mention when not to use it or name alternatives, but the 'same PR' and 'your current change' guidance provides enough usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state idempotentHint=false and readOnlyHint=false, but the description adds valuable context: it records a new proposal each call (non-idempotent) and explicitly assures that it does NOT modify the repository or open a PR. It also reveals that the tool resolves a target path and returns content for the user to write, which is a non-obvious behavioral trait. This goes beyond the annotations, though it doesn't mention permissions or rate limits.
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 well-structured and front-loaded with the primary purpose. Each sentence contributes meaning: purpose, non-idempotency, non-modification behavior, the resolution process, the return value, and the parameter constraint. While it is longer than the two-sentence high example, it packs substantial necessary detail without fluff, and the repetition of the return value is minor but not wasteful.
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 (7 parameters, side effects, resolution logic), the description covers the core workflow well: it tells the user what to do (propose), what to expect (resolved path and content), and a key constraint (targetPath or baseSlug). It does not explain edge cases like the repository parameter behavior (covered in the schema) or what happens if both targetPath and baseSlug are provided, but that is not critical. The return value is minimally described, which is sufficient given no 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 input schema already provides descriptions for all 7 parameters (coverage 100%), so the baseline is 3. The description adds the mutual exclusivity rule 'Provide either targetPath or baseSlug', which is not in the schema, and clarifies the return value (resolved path and content). This enriches the parameter semantics without repeating the schema's field 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: to propose a documentation file to add or update. It specifies the verb 'propose' and the resource 'documentation file', and distinguishes itself from sibling tools by focusing on add/update rather than removal or read-only queries. It also clarifies that it returns a path and content for the user to write, making its role 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 gives clear context for when to use this tool: as part of the current change, when adding or updating docs, and it explains the workflow (returns path and Markdown for the user to write). It does not explicitly name alternatives (like propose_doc_removal) or state when not to use it, but the sibling context and the 'Propose...' phrasing imply the appropriate use case. It also provides a key constraint: provide either targetPath or baseSlug.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Self-review a change you are about to commit BEFORE opening the PR. Pass the proposed new state of each changed file (and any deleted paths); Moxie returns a severity-ranked list of violations to fix: convention breaches, docs your change makes factually false, net-new API/surface added without docs, and doc references broken by deletions. Read-only; no side effects and no writes. Returns a Markdown verdict (clean | warnings | must-fix) with each finding's location, fix, and - for doc issues - the slug to pass to propose_doc_update. Call this as the final step of the edit flow, then fix findings and re-run.
| 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. | |
| changedFiles | Yes | The files your change adds or modifies, in their PROPOSED new state. Provide newContent (the full new file text) for each; you may also/instead provide patch (a unified diff). Max 20 files per call. | |
| deletedPaths | No | Repository-relative paths your change DELETES, so Moxie can flag docs whose references break. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Read-only; no side effects and no writes,' which aligns with annotations (readOnlyHint, destructiveHint, idempotentHint). It further discloses what the tool checks (convention breaches, docs made false, net-new API without docs, broken refs) and the output format (Markdown verdict with locations, fixes, and slugs), adding value 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?
The description is a single dense paragraph that front-loads the purpose and usage. It efficiently covers what it does, what output to expect, and how to proceed. Every sentence adds value without redundancy, achieving conciseness despite the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully explains the tool's behavior, inputs, outputs, and usage context. It details the categories of violations, the Markdown verdict format, and the workflow. No output schema exists, but the description compensates by describing the return structure, making the tool comprehensible and actionable.
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 parameters are well-documented in the schema itself. The description restates 'Pass the proposed new state of each changed file' and mentions 'deleted paths,' but does not add semantic details beyond what the schema already provides (e.g., newContent vs patch, max 20 files). Per the rubric, with high schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Self-review a change') and specific resource ('about to commit BEFORE opening the PR'). It distinguishes from siblings by explaining it returns a severity-ranked list of violations and explicitly mentions propose_doc_update for doc issues, making it distinct from read-only retrieval tools like get_conventions or get_doc_gaps.
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 gives explicit timing guidance: 'BEFORE opening the PR' and 'Call this as the final step of the edit flow, then fix findings and re-run.' It also implies the workflow by noting that doc issues produce a slug for propose_doc_update, indirectly indicating that tool for follow-up. This is clear when-to-use and provides an alternative path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Read-only; no side effects' is consistent with those. Beyond the annotations, it adds valuable behavioral context: results are 'ranked matches in Markdown grouped into Documentation and Code sections, each with a title, snippet, and source paths,' and omitting query returns recent context. This goes beyond the structured safety hints without fully covering all edge behaviors like pagination.
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, front-loaded with the core purpose, then safety, then return format, then usage guidance. Every sentence carries unique information: scope, output structure, when-to-use alternatives, and edge-case behavior. No repetition or filler beyond a short safety reinforcement.
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 thoroughly explains return values (Markdown, grouped sections, title/snippet/source paths) and covers key invocation scenarios (open-ended lookup, omit query, specific getter alternatives). The rich schema covers parameter details and the annotations cover the safety profile, so nothing critical is left unexplained for a search 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 description coverage is 100%, so all three parameters (limit, query, repository) are already documented with defaults, ranges, and fallback behaviors. The main description reinforces the query-omission behavior and result grouping but adds little parameter-level meaning beyond the schema, so the 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 opens with a specific verb and scope: 'Keyword and semantic search across the connected repository's generated docs, conventions, documentation gaps, AI-context notes, and indexed code.' It clearly enumerates what is searched and differentiates from sibling getters by framing itself as the open-ended discovery tool, matching the annotation title 'Search docs and code.'
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 is provided: '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.' It names concrete alternatives and also discloses the edge-case behavior of omitting query, giving the agent clear decision rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
moxie.get_api_contextmoxie.review_changemoxie.get_ai_context1 field changedInput schema / properties / repository / descriptionPrevious value: -"Optional owner/name reference like \"acme/app\". Required only when the token is authorized for multiple repos and no default is set."New value: +"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."moxie.get_conventions1 field changedInput schema / properties / repository / descriptionPrevious value: -"Optional owner/name reference like \"acme/app\". Required only when the token is authorized for multiple repos and no default is set."New value: +"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."moxie.get_doc_gaps2 fields changedInput schema / properties / repository / descriptionPrevious value: -"Optional owner/name reference like \"acme/app\". Required only when the token is authorized for multiple repos and no default is set."New value: +"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."Input schema / properties / severity / descriptionPrevious value: -"Optional severity filter."New value: +"Optional severity filter: high, medium, low, or info."moxie.get_doc_impact1 field changedInput schema / properties / repository / descriptionPrevious value: -"Optional owner/name reference like \"acme/app\". Required only when the token is authorized for multiple repos and no default is set."New value: +"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."moxie.get_documentation_opportunities1 field changedInput schema / properties / repository / descriptionPrevious value: -"Optional owner/name reference like \"acme/app\". Required only when the token is authorized for multiple repos and no default is set."New value: +"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."moxie.get_documentation_patterns1 field changedInput schema / properties / repository / descriptionPrevious value: -"Optional owner/name reference like \"acme/app\". Required only when the token is authorized for multiple repos and no default is set."New value: +"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."moxie.list_docsmoxie.propose_doc_removal1 field changedInput schema / properties / repository / descriptionPrevious value: -"Optional owner/name reference like \"acme/app\". Required only when the token is authorized for multiple repos and no default is set."New value: +"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."moxie.propose_doc_update1 field changedInput schema / properties / repository / descriptionPrevious value: -"Optional owner/name reference like \"acme/app\". Required only when the token is authorized for multiple repos and no default is set."New value: +"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."moxie.search_docs3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum matches to return."New value: +"Maximum matches to return (1-20, default 8)."Input schema / properties / query / descriptionPrevious value: -"Search phrase or topic."New value: +"Search phrase or topic. Omit to return recent context for the repository."Input schema / properties / repository / descriptionPrevious value: -"Optional owner/name reference like \"acme/app\". Required only when the token is authorized for multiple repos and no default is set."New value: +"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."moxie.get_ai_contextmoxie.get_conventionsmoxie.get_doc_gapsmoxie.get_doc_impactmoxie.get_documentation_opportunitiesmoxie.get_documentation_patternsmoxie.propose_doc_removalmoxie.propose_doc_updatemoxie.search_docsClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
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
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
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!
Add one secure layer between your agents and this server.
Tools are mostly distinct by scope and intent, but get_doc_gaps overlaps with get_documentation_opportunities as a subset, and get_ai_context partially overlaps with conventions and gaps. The descriptions explicitly clarify these relationships, so an agent can usually pick correctly.
All tools use a clear verb-prefixed snake_case pattern: get_, list_, propose_, review_, and search_. The naming is uniform and predictable across the entire set.
12 tools is well within the ideal range for a documentation-assistant server. Each tool covers a distinct aspect of the workflow: discovery, context, targeted impact, proposals, and review.
The surface covers the full docs workflow: browse and search docs, retrieve conventions/gaps/opportunities, get location guidance, propose updates/removals, and review changes before commit. There are no obvious dead ends for the server's stated purpose.