Extracts Angular route guards and frontend access-control rules from source code.
Extracts Django endpoints, ORM data models, access-control decorators and permission classes, and Django template rules.
Extracts data model definitions from Drizzle ORM schemas.
Extracts Express endpoints and access-control middleware.
Extracts FastAPI endpoints and follows dependency-based access-control chains.
Extracts Fastify endpoints.
Extracts Flask endpoints and access-control decorators.
Extracts Gin endpoints.
Parses GraphQL SDL to recover endpoints, data model types, and access-control information.
Extracts JPA/Hibernate entity data models.
Extracts Hono endpoints.
Extracts Koa endpoints.
Extracts Laravel endpoints, Eloquent data models, middleware/Spatie access control, and Blade template rules.
Extracts data models from Mongoose schemas.
Extracts NestJS controllers/resolvers, guards, and role access-control decorators.
Extracts ASP.NET Core endpoints and [Authorize] access-control attributes.
Detects Next.js route handlers and pages/api endpoints.
Extracts entities, fields, keys, and relations from Prisma schemas.
Reads React conditional rendering and RequireRole-style components for frontend access rules.
Extracts data model definitions from Sequelize models.
Extracts Spring MVC endpoints and @PreAuthorize or request-matcher access-control rules.
Extracts data models from SQLAlchemy models.
Extracts tRPC endpoints.
Extracts data models from TypeORM entities.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@business-overview Scan /workspace/my-app and list the roles and their access."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Point it at a codebase. Get back what the software actually does, who is allowed to do it, and where the rules are missing.
An MCP server that reads source code and answers the questions a founder, a product owner, or a new engineer actually asks: what features exist, what can each role do, what data do we hold, and what did we build that nobody uses?
It was written for a specific problem. AI coding agents now ship features faster than anyone can keep track of them. The code works, but nobody holds the full picture any more: which roles exist, what each one can reach, which rules are enforced on the server and which only in the UI. This reads the code and rebuilds that picture, with a file and line number behind every claim.
No LLM is required. Everything below is extracted from source with parsers, so it is fast, free, and deterministic. Claude is optional, and only adds the narrative layer on top.
scan_project root=/path/to/project → features, roles, endpoints, data, stack
generate_report root=/path/to/project → a shareable HTML report
A role × feature access matrix. Who can reach what, at a glance. ● full access, ◐ partial, ○ none.
Findings that point at real problems, each with a file and line: rules enforced only in the browser, roles defined but never checked, write endpoints with no authentication, inconsistent rules on the same resource, tables nothing reads.
A data model you did not have to draw. Entities, fields, keys and relations, recovered from whichever ORM the project uses.
Plus a feature inventory, use cases per role, a C4 container diagram, a module dependency graph, and per-endpoint sequence diagrams. Diagrams come out as Mermaid or PlantUML, so they render in GitHub, VS Code, Notion and Confluence, and the report is a single self-contained HTML file you can email to someone non-technical.
Related MCP server: Codebase Insights MCP Server
Node 20+, or Docker if you prefer not to install anything.
git clone https://github.com/fadiroot/business-overview-mcp.git
cd business-overview-mcp
npm install
npm run buildclaude mcp add business-overview -- node /absolute/path/to/business-overview-mcp/dist/index.jsThen ask it in plain language:
Use business-overview to scan /path/to/my/project and tell me what each role can do.
Or run one of the bundled prompts: business_overview, feature_deep_dive, access_review.
{
"mcpServers": {
"business-overview": {
"command": "node",
"args": ["/absolute/path/to/business-overview-mcp/dist/index.js"]
}
}
}docker build -t business-overview-mcp .
claude mcp add business-overview -- \
docker run -i --rm -v /path/to/your/projects:/workspace business-overview-mcpYour code is mounted at /workspace, so call the tools with root: "/workspace/my-project".
This repository ships a small demo application, examples/nimbus-lms, with a NestJS-style API, a Prisma schema, a React frontend, and five planted problems. Scan it and you should find every one of them:
scan_project root=<repo>/examples/nimbus-lms
audit_findings root=<repo>/examples/nimbus-lmsEvery screenshot above is that demo, unedited.
Tool | What it answers |
| What is this, what is it built with, what are the features? Start here. |
| Every endpoint with the guards, roles and permissions protecting it. Filter by feature, by role, or to unprotected ones only. |
| Roles, permissions, guards, path rules, backend and frontend checks, and the access matrix. |
| Entities, fields, relations and enums. |
| What each actor can accomplish, grouped by feature. |
| Over-build and access gaps, ranked by severity. |
| One feature end to end, with a sequence diagram of its main flow. |
|
|
| The full HTML and Markdown report. |
Detection is heuristic, built on parsers rather than a language server, so it runs in seconds on a large repository and degrades gracefully when it meets something it does not recognise.
Supported | |
Endpoints | Express, Fastify, Koa, Hono, NestJS (controllers and resolvers), Next.js route handlers and |
Data model | Prisma, TypeORM, Mongoose, Drizzle, Sequelize, Knex, SQLAlchemy, SQLModel, Django ORM, Eloquent, Laravel migrations, JPA and Hibernate, GORM, raw SQL DDL, GraphQL types |
Access control | Role enums and constants, NestJS guards and decorators, Express middleware, FastAPI dependencies (followed through their own chains), Flask and Django decorators and permission classes, Laravel middleware and Spatie, Gates and Policies, Spring |
Frontend rules |
|
list_use_cases and generate_report accept mode: "claude". With ANTHROPIC_API_KEY set, the extracted facts go to Claude, which merges raw endpoints into real business use cases and returns what each role can and cannot do, which features look questionable, and the questions the owner should answer. Without a key, both tools fall back to the deterministic output and say so.
claude mcp add business-overview -e ANTHROPIC_API_KEY=sk-ant-... -- \
node /absolute/path/to/business-overview-mcp/dist/index.jsWorth knowing before you act on the output.
"Public" means no guard was recognised, not proof that an endpoint is open. Custom auth wrappers can be missed. Verify high-severity findings against the file and line given.
Role to permission mappings held in a database (Spatie tables, for example) cannot be resolved from source. Those cells show ?.
Features are inferred from directory structure. Feature folders, layered and hexagonal layouts, and monorepos are handled; unusual layouts may group oddly.
Diagrams cap how much they draw to stay readable. Pass feature to zoom into one area.
npm run build
npm run smoke # analyse the test fixtures and print everything
npm test # drive the server over MCP and assert the resultsfixtures/ holds two small projects used by the tests, one NestJS and Prisma, one FastAPI and SQLAlchemy. examples/nimbus-lms is the larger demo.
Issues and pull requests are welcome, especially for frameworks that are not detected yet. A fixture that reproduces the gap is the most useful thing you can send.
MIT
Over-build and access-control gaps: unprotected writes, roles/permissions defined but never checked, orphan entities, UI-only restrictions, inconsistent restrictions, duplicate endpoints, size outliers, features without behaviour.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Absolute path of the project to analyse (a mounted path such as /workspace when running in Docker). | |
| format | No | Output format (default markdown). | |
| refresh | No | Re-scan the project instead of using the cached analysis. | |
| severity | No | Minimum severity to include. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, yet it only lists output categories. It does not state that the tool is read-only, that it caches by default, or what kind of report it produces, all of which matter for an audit tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The text is compact and free of filler, but it is a bare noun phrase followed by a colon and a list rather than a well-formed sentence. It is concise in word count, not in communicative structure, and the telegraphic style hurts clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description does not explain the return value, the effect of format and severity parameters, or how this tool relates to siblings. The schema documents parameters, but the surrounding usage context is missing.
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 documents all four parameters with 100% coverage, so the description need not repeat them. The description also adds no extra meaning about root, format, refresh, or severity beyond what the schema already provides, making the baseline 3 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 identifies a concrete subject area—over-build and access-control gaps—and enumerates specific finding categories such as unprotected writes and orphan entities, so it is not a tautology. However, it contains no verb and never explicitly says the tool audits, finds, or reports these issues; an agent must infer the action from the tool name.
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?
There is no guidance about when to use this tool versus alternatives. Given siblings like scan_project and extract_access_control, the description does not help an agent decide between auditing for gaps and simply extracting access-control definitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deep dive on one feature: purpose signals, endpoints, use cases, roles, entities, files, findings and a sequence diagram for its main write endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Absolute path of the project to analyse (a mounted path such as /workspace when running in Docker). | |
| feature | Yes | Feature name as listed by scan_project. | |
| refresh | No | Re-scan the project instead of using the cached analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden. It does not explicitly state that the tool is read-only or non-destructive, but the nature of an 'explain' tool suggests safety. The description mentions it provides a sequence diagram and various analyses, which are outputs, but does not disclose caching behavior or performance implications. The refresh parameter in the schema indicates caching, but that is not in the description itself. The description adds some behavioral context but misses explicit side-effect disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core purpose ('Deep dive on one feature') and then lists the coverage areas. It is concise, though the list of seven items is a bit long. The structure is clear and efficient, with no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers a wide range of what is returned (purpose, endpoints, use cases, roles, entities, files, findings, sequence diagram). It does not mention the output format (structured object vs text) or prerequisites beyond the feature name coming from scan_project, which is in the schema. The refresh behavior is in the parameter description. Overall, it is fairly complete for an analysis tool, though it could be more explicit about the output structure.
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 all parameters (root, feature, refresh) have descriptions in the schema. The tool description adds no extra meaning beyond what the schema provides; it does not clarify parameter relationships or usage nuances. Baseline 3 is appropriate because the schema already documents the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('deep dive') and resource ('one feature'), and enumerates the concrete deliverables: purpose signals, endpoints, use cases, roles, entities, files, findings, and a sequence diagram. This clearly distinguishes it from siblings like scan_project (which presumably scans broadly) and extract_endpoints (which only extracts endpoints). It is not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Deep dive on one feature' implies it is for in-depth analysis of a single feature, which suggests when to use it, but it does not explicitly contrast with alternatives or state when not to use it. There is no mention of other tools like extract_data_model or generate_diagram. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Roles, permissions, guards/policies, path-level rules, backend and frontend access checks, and the role × feature access matrix.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Absolute path of the project to analyse (a mounted path such as /workspace when running in Docker). | |
| format | No | Output format (default markdown). | |
| refresh | No | Re-scan the project instead of using the cached analysis. | |
| include_checks | No | Include the raw list of inline checks (can be long). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only lists output content and does not state whether the tool scans the codebase, whether it is read-only, how caching/refresh works, or what side effects may occur. This is a significant transparency gap for an analysis tool with four parameters.
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 list with no filler words, and every listed term is relevant to access control. It is efficient and front-loaded with the most concrete facets, but it is a fragment rather than a complete sentence, which limits its informational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, four parameters, and a sibling set of extraction/analysis tools, the description is incomplete. It covers what content is produced but omits the action performed, when to use it, behavioral traits, and how it differs from siblings, so an agent lacks critical context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, documenting root, format, refresh, and include_checks with clear descriptions and an enum. The tool description adds little parameter-level meaning, though its mention of 'access checks' loosely aligns with the schema's 'inline checks' parameter. With high schema coverage, 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 enumerates concrete access-control artifacts—roles, permissions, guards/policies, path-level rules, frontend/backend checks, and the role × feature matrix—making the tool's subject unmistakable and distinct from sibling extraction tools. However, it is a noun phrase rather than a sentence with a verb, so the action relies on the tool name 'extract_access_control' rather than being stated in the description itself.
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 no guidance on when to use this tool versus alternatives such as extract_data_model or extract_endpoints. No explicit conditions, prerequisites, or exclusion criteria are provided, so an agent must infer the intended use case solely from the tool name and content list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Entities, fields and relations from Prisma, TypeORM, Mongoose, Drizzle, Sequelize, Knex, SQLAlchemy, Django, Eloquent, Laravel migrations, JPA, GORM, SQL DDL and GraphQL SDL.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Absolute path of the project to analyse (a mounted path such as /workspace when running in Docker). | |
| format | No | Output format (default markdown). | |
| feature | No | Only entities belonging to this feature. | |
| refresh | No | Re-scan the project instead of using the cached analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that a cache can be used (via the refresh parameter), but does not explain the analysis process, potential side effects (e.g., reading many files), or what happens with unsupported ORMs. This is minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence listing the supported frameworks, which is efficient. It is front-loaded with the key resource, and every word adds value. It could be slightly more structured but is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a moderate complexity (4 params), the description is adequate but leaves gaps. It doesn't explain the output format or that the tool may perform a scan, which could surprise the agent. The parameter list is clear, but behavioral aspects like caching are only hinted at via the refresh parameter.
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 each parameter is described in the schema. The description adds context by linking the tool to a broad set of ORMs, which clarifies the 'root' parameter's scope. However, the 'feature' parameter's meaning is not elaborated beyond the schema, but the schema is sufficient.
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 identifies a specific action ('extract') on a resource ('data model') and lists many supported ORMs and frameworks, which clearly communicates what the tool analyzes. However, it does not explicitly contrast with siblings like extract_endpoints or explain_feature, though the resource focus is fairly distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for extracting data models from various ORMs, but does not state when to prefer this over alternatives like scan_project or explain_feature. There is no explicit when-not-to-use guidance, leaving some ambiguity for an agent choosing among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
HTTP/GraphQL/tRPC endpoints with the guards, roles and permissions that protect them. Supports Express-style routers, NestJS, Next.js, tRPC, FastAPI, Flask, Django (+DRF), Laravel, Spring, ASP.NET Core, Go routers, Rails and GraphQL SDL.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | Only endpoints this role may call. | |
| root | Yes | Absolute path of the project to analyse (a mounted path such as /workspace when running in Docker). | |
| format | No | Output format (default markdown). | |
| feature | No | ||
| refresh | No | Re-scan the project instead of using the cached analysis. | |
| unprotected_only | No | Only endpoints with no detected authentication. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It says what is returned (endpoints with protections) but not how the tool behaves: it does not mention that it scans a project, may use caching, or could be resource-intensive. The refresh parameter hints at caching, but the description itself adds little behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core purpose before listing supported frameworks. It is concise and information-dense without being verbose, though the long framework list could be considered slightly bulky.
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 absence of an output schema and annotations, the description does not fully explain return values or edge cases. It covers the primary resource and supported stacks, and the input schema fills some gaps, but the undocumented feature parameter and lack of guidance on cached results or unsupported frameworks make it only moderately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so most parameters are already documented in the input schema. The description adds context that endpoints may have guards, roles, and permissions, which enriches the meaning of role and unprotected_only. However, it does not clarify the undocumented 'feature' parameter, and the description mostly reinforces schema information rather than adding significant new semantic detail.
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 identifies the resource: HTTP/GraphQL/tRPC endpoints along with their guards, roles, and permissions. This distinguishes it from siblings like extract_data_model and extract_access_control. While the action verb 'extract' is not explicitly stated in the description, the tool name and title supply it, making the purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage contexts by listing supported frameworks (Express, NestJS, Next.js, tRPC, etc.), so an agent can infer when it applies. However, it does not explicitly compare against alternatives like extract_access_control or state when not to use it, leaving some inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a diagram as Mermaid or PlantUML source. Types: erd (data model), use_case, architecture (C4 container), role_access (roles → features), overview (actors → features → data), module_dependencies (import graph between features), feature_map (mindmap), sequence (one endpoint's request flow). Writes .mmd/.puml + .html viewer to out_dir and returns instant preview links (mermaid.live, kroki.io, plantuml.com).
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Absolute path of the project to analyse (a mounted path such as /workspace when running in Docker). | |
| type | Yes | ||
| write | No | Write files to out_dir (default true). | |
| format | No | Default mermaid. PlantUML supported for erd, use_case, architecture. | |
| feature | No | Restrict to one feature (erd, use_case, role_access, sequence). | |
| out_dir | No | Where to write files (default <root>/docs/business-overview/diagrams). | |
| refresh | No | Re-scan the project instead of using the cached analysis. | |
| endpoint | No | For sequence: "METHOD /path". | |
| render_svg | No | Also render SVG with mermaid-cli (mmdc) if installed. | |
| max_entities | No | ||
| include_fields | No | ERD: include all fields (default true) or only keys. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly discloses that the tool writes .mmd/.puml and .html files to out_dir and returns preview links, and mentions caching behavior via the 'refresh' parameter. It does not mention potential side effects like overwriting files or permission requirements, but the core behaviors are transparent enough.
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 main purpose and then enumerates types and output behavior. It is concise, with no wasted words, but packs a lot of information. It earns its place and is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters and no output schema or annotations, the description covers the core purpose, output format, and diagram type selection. It does not explicitly explain the interplay of parameters like 'endpoint' with 'sequence' or the caching implications, but given the schema coverage, it is sufficiently complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 82%, so most parameters are already described. The description adds value by clarifying the meaning of the 'type' parameter through the list of diagram types, and by explaining output generation. It enhances the semantics of 'type' and 'format' beyond the schema, but does not compensate for the few undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates diagrams in Mermaid or PlantUML, enumerates eight specific diagram types with brief parenthetical explanations, and distinguishes it from sibling extraction tools. It uses a specific verb ('generate') and resource ('diagram') with sufficient detail to avoid confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use each diagram type by listing them with contextual hints (e.g., 'erd (data model)', 'sequence (one endpoint's request flow)'). However, it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. The guidance is implicit but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a self-contained HTML report (plus Markdown and optional JSON facts) with executive summary, feature inventory, actors & roles, use cases, role × feature access matrix, restrictions, ERD, C4 architecture, module dependencies, endpoint catalogue and findings. mode=claude adds Claude's narrative analysis and owner questions.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| root | Yes | Absolute path of the project to analyse (a mounted path such as /workspace when running in Docker). | |
| formats | No | ||
| out_dir | No | Default <root>/docs/business-overview | |
| refresh | No | Re-scan the project instead of using the cached analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does well by specifying the output artifact, its self-contained nature, and the effect of mode=claude (narrative analysis and owner questions). It does not mention file-writing side effects or cached-analysis behavior, but those are partially inferable from the schema's out_dir and refresh.
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 main sentence front-loads the action and then lists many concrete report components; every item is substantive and non-redundant. It is dense rather than perfectly scannable, but there is 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?
The description thoroughly covers what the report contains and how mode changes output, but it omits workflow context such as relying on scan_project/cached analysis and when to prefer this tool over sibling extraction tools. The schema fills some gaps (root, out_dir, refresh), leaving an adequate but not fully complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents root, out_dir, and refresh, while enums cover mode and formats. The description adds useful meaning for mode ('mode=claude adds Claude's narrative analysis and owner questions') and maps formats to 'HTML, Markdown and optional JSON facts', but it does not clarify defaults or the relationship between formats and the listed deliverables.
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 action and resource ('Write a self-contained HTML report') and enumerates the exact report sections, making its purpose concrete. It is clearly distinct from sibling extraction tools like extract_endpoints and from generate_diagram.
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?
There is no guidance on when to call generate_report versus scan_project, extract_*, or generate_diagram, nor whether it should follow a prior scan. The only condition mentioned is the intra-tool mode=claude option, which is parameter-level rather than tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Business use cases derived from endpoints + roles. mode=heuristic is instant and deterministic; mode=claude asks Claude to merge/rename them into real business use cases with preconditions, flows, restrictions and a feature assessment (needs ANTHROPIC_API_KEY on the server).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| root | Yes | Absolute path of the project to analyse (a mounted path such as /workspace when running in Docker). | |
| actor | No | Filter by actor/role name. | |
| format | No | Output format (default markdown). | |
| feature | No | ||
| refresh | No | Re-scan the project instead of using the cached analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It meaningfully discloses that heuristic mode is deterministic, claude mode delegates to Claude and requires ANTHROPIC_API_KEY, and claude mode produces preconditions, flows, restrictions, and feature assessments. It stops short of mentioning caching/refresh behavior or external API side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the purpose before diving into mode details. It earns its place, though the single dense sentence could be slightly clearer if broken into two sentences or bullets.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and multiple mode-dependent behaviors, the description leaves gaps: it does not mention the default mode, whether a prior scan is required, how refresh affects caching, or the shape of the returned use cases. The provided info is enough for basic heuristic use but not fully self-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?
The description adds real semantics for the mode parameter, explaining what each enum value does. The schema already documents root, actor, format, and refresh, but the feature parameter is undocumented in both the schema and the description, and no default mode is specified.
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 identifies the resource ('business use cases') and its source ('endpoints + roles'), which is specific enough to distinguish the tool from siblings. Though the verb 'list' appears only in the title, the meaning is clear and the two modes are explained.
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 practical mode-selection guidance: heuristic is instant and deterministic, while claude merges/renames into richer use cases and requires an API key. However, it does not explain when to choose this tool over siblings like extract_endpoints or explain_feature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index a codebase: languages, frameworks, databases, external services, features (modules) and headline counts of endpoints, entities, roles and findings. Run this first.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Absolute path of the project to analyse (a mounted path such as /workspace when running in Docker). | |
| format | No | Output format (default markdown). | |
| refresh | No | Re-scan the project instead of using the cached analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It transparently states the main action (indexing) and the scope of what is indexed, and the 'Run this first' hint suggests workflow dependency. However, it does not mention that results are cached or whether the operation is non-destructive; the refresh parameter hints at caching, but the description itself omits it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler: the first packs the tool's purpose and scope, the second delivers the key workflow instruction. Information is front-loaded and 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?
The description, combined with the fully documented schema, covers invocation essentials and gives clear ordering advice. It does not detail the exact output structure, but with no output schema and a clear 'index' scope, this is a minor gap rather than a critical omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for all three parameters (root, format, refresh), so the baseline is 3. The description does not add parameter-level detail beyond what the schema already documents.
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?
Uses a specific verb 'Index' with a clear resource 'a codebase' and enumerates the indexed categories (languages, frameworks, databases, external services, features, and headline counts). The broad inventory and 'Run this first' distinguish it from the more focused sibling extraction and report 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?
Explicitly instructs 'Run this first,' which gives clear ordering context relative to sibling tools. It does not name alternative tools or state when not to use it, but the primacy directive is strong practical guidance for an agent.
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.
v0.1.0audit_findingsexplain_featureextract_access_controlextract_data_modelextract_endpointsgenerate_diagramgenerate_reportlist_use_casesscan_projectScored across 9 tools
Each tool targets a distinct phase or concern: scanning, extracting a specific artifact, explaining a feature, auditing, diagramming, and reporting. The only potential overlap is between extraction tools and diagram generation, but one extracts facts and the other visualizes them, so the boundaries are clear.
All tool names follow a consistent lowercase snake_case verb_noun pattern: scan_project, extract_data_model, explain_feature, generate_diagram, generate_report. The verbs are specific and match the action each tool performs, making the set predictable.
Nine tools is well-scoped for a codebase analysis and reporting server. Each tool earns its place, covering ingestion, analysis, and output generation without redundancy or bloat.
The tool surface covers the full analysis pipeline from initial project scan, through data model/endpoint/access control extraction, to use cases, findings, diagrams, and final reports. There are no obvious dead ends or missing capabilities for the stated business-overview purpose.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Enterprise code intelligence for M&A, security audits, and tech debt. Hosted server with 200k free.
Threat modeling, code/cloud/pipeline scanning, shadow-AI discovery, compliance checks and fixes.
