SHPBL: Repository Audit & Repair

Audit a repository

evaluate_repo

Read-onlyIdempotent

Audit any GitHub repository and get back one complete result: a report (inventory, languages, spine files, risk signals), the capabilities found in it (name, signature, file and line, stated contract, dependencies), and how it stands against SHPBL's anonymous corpus of audited repositories. Works with no key: every caller gets the whole diagnosis of their own repository. A free run stops at the composition boundary — neither library is searched, so no library rows, candidates, parents or proposed architecture are returned — and nothing is retained (no pull request, no export, no recorded run). A Practitioner key (7-day free trial) continues past that boundary: both libraries searched, candidates identified and composed, and the result written back to your own repository. Whatever a run finds is yours. Follow with fix_repo for verbatim source and diffs, harvest_repo for the whole tree.

Input Schema

TableJSON Schema

Name	Required	Description
`key`	No	Your SHPBL key (shpbl_mcp_…), if you have one. Optional — without it the audit runs at the free depth. Also read from the `Authorization: Bearer …` header.
`repo`	Yes	A GitHub repository: `owner/repo`, a github.com URL, or `owner/repo#branch`.
`brief`	No	Default true: keep the audit compact and do not include the full method protocol. Set false to include the protocol block.
`as_free`	No	Run at the free depth even when the key carries a paid tier, so you can see exactly what a caller without a subscription is handed. Costs no allowance and changes nothing else about the audit.
`own_library`	No	Your own previously harvested capabilities, read out of your repository's `.shpbl/` library and passed back in. Optional. When present, this run checks your concerns against your own library first and tells you which ones you already solved. It is held in memory for this call only — never stored, never added to SHPBL's library.
`github_token`	No	Optional GitHub token (Contents: read) for a private repository. Not needed if the owner connected the SHPBL GitHub App to this key at https://shpbl.com/mcp-access.
`protocol_ack`	No	Set true to say you already hold the SHPBL protocol. The discipline, the ten meta capabilities, the hands-off list and the return shape are then not reprinted even when `brief: false` — they are unchanged and they still bind the run.

TDQS

A3.5/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, but the description says a Practitioner key's result is 'written back to your own repository' and contrasts that with free runs producing 'no pull request, no export, no recorded run'. This directly implies a state mutation, contradicting the read-only annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but well-structured: the result shape is front-loaded, followed by free/paid behavior, retention, and sibling routing. Minor redundancy with the key schema and the somewhat promotional 'Whatever a run finds is yours' keep it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and a complex 7-parameter tool, the description provides a meaningful high-level return shape (report, capabilities, corpus comparison) and explains conditional depth, retention, and write-back behavior. It lacks an exact result schema or error behavior, but is adequate for invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 7 parameters. The tool description adds tier context for the key but largely repeats what the key parameter's schema already says; it does not substantially deepen parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Audit any GitHub repository and get back one complete result', then enumerates the result contents (report, capabilities, corpus comparison). It also names the sibling follow-ups fix_repo and harvest_repo, which makes the tool's role distinct from extraction and remediation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes the free-depth vs Practitioner-key execution paths and what changes at the composition boundary, so an agent knows when a key is needed. It names follow-up tools, though it does not explicitly contrast with library_search or other audit-adjacent siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All SHPBL: Repository Audit & Repair tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.8/5.0

Disambiguation4/5

Most tools target distinct stages or resource types: evaluate/fix/harvest are clearly separate audit phases, and write_to_repo/list_repos are unambiguous. The library_* trio is mostly separable but library_document and library_index both offer access to volumes, and run_gauntlet partially overlaps the individual stage tools, so a couple of boundaries are less crisp.

Naming Consistency4/5

Names are uniformly lowercase snake_case and mostly follow a verb_noun pattern: evaluate_repo, fix_repo, harvest_repo, write_to_repo, list_repos, run_gauntlet. A few are noun_noun or resource-prefixed like library_search, library_document, subscription_status, and welcome/selfcheck_mcp are one-offs, so it is predictable but not perfectly uniform.

Tool Count5/5

At 14 tools the server sits within the ideal 3-15 range, and each tool has a plausible role in the audit/repair, library, or operational workflow. The count is on the larger side but justified by separate free and Practitioner lanes, library services, and health/status checks.

Completeness4/5

The core audit lifecycle is well covered: list/scope, evaluate, fix, harvest, write back, plus library search and run orchestration. The main gap is that build_intent explicitly gates COMPOSE/SPECIALIZE/CREATE operations, but no actual compose/specialize/create tools are exposed, and there is no explicit run_gauntlet cancellation or reset, though agents can work around both.

Resources

Need Help?