This server is an OSS Autopilot MCP exposing tools to monitor, triage, and act on GitHub pull requests and issues.
Daily PR monitoring: Run daily to fetch and prioritize open PRs by CI status, reviews, and conflicts.
Track and manage PRs: Track/untrack PRs, shelve/unshelve them, move them between attention/waiting/shelved states, and mark notifications as read.
Read PR context: Fetch comments on a PR, including optional bot comments.
Search and vet issues: Search for beginner-friendly issues matching your interests, and vet a specific issue for contribution suitability.
Interact on GitHub: Post comments on issues/PRs and claim issues with a custom or default message.
Configuration and setup: Initialize with a username, run setup, check setup status, inspect/update config values, and run startup checks.
Dismiss/undismiss issues: Silence or restore notifications for specific issues.
Provides automated triage for Dependabot alerts and pull requests as part of a headless workflow for maintaining open-source repositories.
Monitors GitHub pull requests to track CI failures, merge conflicts, and maintainer feedback, while identifying new open-source contribution opportunities based on the user's history and repository health.
If you contribute to more than a couple of projects, PRs go stale without you noticing. A maintainer asks for a change, CI breaks after a rebase, a branch picks up a conflict, and you find out two weeks later.
OSS Autopilot checks every open PR you have on GitHub and sorts them into what needs you and what is waiting on someone else. For the ones that need you, it helps draft the reply, diagnose the CI failure, or rebase the branch. You approve each push and each comment before it goes out.
Related MCP server: jt-mcp-server
Node.js 22 or newer
GitHub CLI installed and logged in (gh auth login), or a GITHUB_TOKEN in your environment
For the plugin: Claude Code, plus npm and network access on first run (see below)
CI runs on Ubuntu and macOS. Windows is untested.
/plugin marketplace add costajohnt/oss-autopilot
/plugin install oss-autopilot@oss-autopilotRestart Claude Code, then:
/setup-ossSetup asks for your GitHub username, the languages and labels you care about, and how many PRs you want open at once. After that, run /oss whenever you want to check in.
About the first run. The plugin ships as source. The first /setup-oss or /oss installs dependencies and builds the CLI inside the plugin directory, so it needs npm (or pnpm) and a network connection, and it takes longer than later runs. If the build fails, see Troubleshooting.
Save your GitHub username once:
npx @oss-autopilot/core@latest init <your-github-username>Then add the server to your MCP client config:
{
"mcpServers": {
"oss-autopilot": {
"command": "npx",
"args": ["@oss-autopilot/mcp@latest"]
}
}
}The MCP server exposes 30 tools, 6 resources, and 4 prompts. @latest means you get new releases automatically; pin a version (@oss-autopilot/mcp@5.7.4) if you would rather update on your own schedule.
npx @oss-autopilot/core@latest init <your-github-username>
npx @oss-autopilot/core@latest daily # human-readable digest
npx @oss-autopilot/core@latest daily --json # structured output
npx @oss-autopilot/core@latest doctor # check token, state, rate limit
# or install it
npm install -g @oss-autopilot/core
oss-autopilot --helpEvery command accepts --json and returns { success, data, error, timestamp }, so it is easy to script.
npm install @oss-autopilot/coreimport { runDaily, runSearch } from '@oss-autopilot/core/commands';
const digest = await runDaily();
const issues = await runSearch({ maxResults: 10 });API reference: jcosta.tech/oss-autopilot.
Run /oss.
The CLI fetches your open PRs from GitHub and classifies each one: failing CI, changes requested, unanswered maintainer comment, merge conflict, incomplete checklist, or waiting on the maintainer.
You get a short list with the PRs that need you first, and a menu of actions.
Pick one. An agent reads the thread and the diff, then drafts a reply or prepares a fix.
You read the draft and approve, edit, or discard it. Nothing is pushed or posted until you approve that specific action.
Repeat, or stop. Most days this is a few minutes.
If you are new to this, set maxActivePRs to 3 to 5. A few PRs you respond to quickly do better than many you let sit.
The plugin adds 9 slash commands:
Command | What it does |
| Daily check: what needs attention, then an action menu |
| Find issues to work on, matched to your languages and history |
| Unattended run that prepares fix branches locally and writes a morning report |
| Open the local dashboard in your browser |
| View or edit what the tool has learned about each repo's review preferences |
| Pre-push loop: lint, tests, parallel review agents, fix, repeat until clean |
| The same review loop for an implementation plan, before you write code |
| Configure preferences |
| Quick reference |
Commands: /oss, /oss-search, /oss-overnight, /oss-dashboard, /oss-guidelines, /pr-ready, /plan-ready, /setup-oss, /oss-help
The plugin also ships 8 specialized agents that Claude dispatches for you:
Agent | Job |
| Drafts replies to maintainer feedback |
| Diagnoses CI failures, conflicts, stale reviews; rebases when needed |
| Checks a PR against opensource.guide practices and the repo's own guidelines |
| Reviews your diff before you commit |
| Searches for and vets issues |
| Judges whether a repo is worth your time before you start |
| Looks at your history and suggests where to focus |
| Prepares one fix branch in a local worktree during |
Agents exist only in the Claude Code plugin. MCP and CLI users get the same underlying data through tools and commands.
For a deeper pre-push review, install the optional pr-review-toolkit plugin from the Claude Code marketplace. /pr-ready uses its reviewers in parallel when present and falls back to the built-in pre-commit-reviewer when not.
/oss-search (or oss-autopilot search) looks for open issues that match your configured languages and labels, then vets each candidate: is it already claimed, is there a linked PR, does the repo merge outside contributions, how fast do maintainers respond. Search and vetting live in a separate package, oss-scout.
Two documents explain the scoring so you can see why a repo did or did not show up:
Repo scores: the history score (your own merged and closed PRs in that repo) and the health score (the repo's current activity, review speed, and merge rate).
Anti-LLM policy detection: repos whose CONTRIBUTING, CODE_OF_CONDUCT, or README say they do not accept AI-assisted contributions are skipped.
/oss-overnight runs the daily check unattended. For PRs with a CI failure, a conflict, or requested changes, it prepares a fix branch in a local git worktree and runs the project's tests. It writes a report to ~/.oss-autopilot/reports/, and your next /oss shows it so you can decide what ships.
To schedule it on macOS:
oss-autopilot overnight schedule --install --hour 2--install writes a launchd plist to ~/Library/LaunchAgents/ and prints the launchctl bootstrap command that loads it. It does not load it for you. Without --install it only prints the plist. There is no built-in scheduler for Linux yet; commands/oss-overnight.md describes the invocation to put in a systemd timer.
Read this before scheduling it. The unattended run is started with an allowlist of tools and a deny list that blocks git push, gh pr comment, gh api, npm publish, and similar commands, and it cannot ask you questions. That stops a well-behaved model from writing to GitHub. It is not a sandbox: the run executes each project's test suite with your credentials available, the same as if you ran those tests yourself. If that is more trust than you want to give, run the job as a separate OS user with no push credentials. See commands/oss-overnight.md for the full threat model.
/oss-dashboard opens a local web UI at http://localhost:3000 with your PRs by status, contribution charts, and buttons to shelve or re-prioritize a PR. It binds to loopback only.
Without Claude Code, run it from the CLI (needs @oss-autopilot/core 3.28.1 or newer, and one daily run so there is data to show):
npx @oss-autopilot/core@latest daily
npx @oss-autopilot/core@latest dashboard serveSettings live in ~/.oss-autopilot/state.json under config. Change them with /setup-oss, or from the CLI:
oss-autopilot config # show everything
oss-autopilot config maxActivePRs 5 # set one valueSetting | Default | Description |
| (detected) | Your GitHub username |
| 10 | Open-PR count at which the tool suggests finishing before starting more |
| 30 | Days without activity before a PR is marked dormant |
| 50 | Minimum repo stars to count in stats and charts |
| (chosen at setup) | Languages for issue search |
| (chosen at setup) | Issue labels for issue search |
|
| Squash commits before merge ( |
|
| Repos to leave out of everything |
|
| Orgs to leave out of everything (for example, your employer) |
|
| Repos to rank lower in search without excluding them |
|
| Issue label types to rank higher in search (for example |
|
| Include documentation issues in search |
|
| After a PR merges, extract what the maintainers asked for into per-repo guidelines |
| (none) | Path to your own curated issue list |
|
| Categories to prioritize (nonprofit, devtools, and so on) |
|
| Orgs to prioritize |
Stats and badges. oss-autopilot stats prints your merged-PR numbers; --markdown gives a shareable report and --badge gives shields.io endpoint JSON. For a live profile badge and SVG cards, see oss-widgets.
Sync across machines (optional). State can be stored in a secret GitHub gist instead of only on disk. See oss-autopilot state --help. A secret gist is unlisted, not access-controlled, so anyone with the URL can read it.
One core, three front ends. The plugin calls the CLI with --json. The MCP server imports the same functions. The dashboard is served by the CLI. They share one state file.
The logic is code, not prompts. PR status, CI failure categories (your bug, fork limitation, auth gate, flaky infrastructure), staleness, and repo scores are computed in TypeScript with tests. The model reads structured JSON and does the parts that need language: reading a review thread, drafting a reply, proposing a fix.
Nothing is cached about your PRs. Each run fetches your open PRs fresh from GitHub's Search API and enriches them with CI status, review decisions, and conflict state. Local state holds your config, your merged and closed history, per-repo scores, and learned guidelines.
It is careful with the API. ETag-based HTTP caching, rate-limit backoff, bounded concurrency, and GraphQL batching keep a daily run well inside GitHub's limits.
Text from GitHub is treated as untrusted. Issue bodies, comments, and review text are fenced and labeled before an agent sees them.
More detail: ARCHITECTURE.md. Security model and reporting: SECURITY.md.
Interactive ( | Unattended ( | |
Read your PRs, issues, CI logs | Yes | Yes |
Edit files in a local clone or worktree | When you pick an action | Yes, in a worktree it creates |
Run a project's tests | When you pick an action | Yes |
Push a branch | Only after you approve | Direct |
Post a comment, open or merge a PR | Only after you approve | Direct |
Send data anywhere other than GitHub | No | No |
In interactive use, approval is per action. Approving one reply does not approve the next one.
All data stays in ~/.oss-autopilot/ (files are written 0600, the directory 0700). There is no telemetry.
Start here. It checks your token, the CLI bundle, the state file, and your rate limit:
npx @oss-autopilot/core@latest doctorgh is missing or not logged in
brew install gh # macOS; see https://cli.github.com for other platforms
gh auth loginThe plugin's first-run build failed
find ~/.claude/plugins -name "oss-autopilot" -type d # locate the plugin
cd <that path>/packages/core
npm install
npm run bundleMy PRs do not show up
Run /setup-oss and confirm the GitHub username.
Only PRs you authored are tracked.
Check excludeRepos, excludeOrgs, and minStars.
Updating
Plugin: /plugin update oss-autopilot
MCP and CLI via npx ...@latest: nothing to do
Found a bug? Open an issue with the output of doctor --json.
GitHub only. No GitLab, Bitbucket, or other forges.
1,000-result cap. GitHub's Search API returns at most 1,000 results per query. If you have more than 1,000 open, merged, or closed PRs, the oldest are not counted.
Single user. It tracks one person's PRs. No team views or shared state.
Overnight scheduling is macOS only out of the box.
Bug fixes, new agents, CLI improvements, and documentation are all welcome. CONTRIBUTING.md has setup instructions.
git clone https://github.com/costajohnt/oss-autopilot.git
cd oss-autopilot
pnpm install
pnpm test
pnpm start -- daily --json # run the CLI from source
claude --plugin-dir . # load your checkout as the pluginThe diagrams in this README are generated from the JSON files in docs/diagrams/ with archify. Regenerate them with node docs/diagrams/export-svg.mjs.
Built and used daily by costajohnt. The contributions below were managed with it.
MIT
Check whether OSS Autopilot is properly set up and configured. Returns setup status and any missing configuration.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds that it returns setup status and missing configuration, which is consistent but does not disclose additional behavioral traits beyond the annotation.
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 long, front-loaded with the primary purpose, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately states what is returned (setup status and missing configuration). However, additional detail on the return format or structure would improve completeness for a tool with no parameters.
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 no parameters, so there are no parameters to describe. With schema description coverage at 100%, the description does not need to add parameter info. The baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'check' and the resource 'OSS Autopilot setup', clearly distinguishing it from siblings like 'setup' (which likely performs setup) and 'status' (general status). It specifies the return of setup status and missing configuration.
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?
No guidance is provided on when to use this tool versus alternatives such as 'setup', 'init', or 'status'. The description lacks explicit context for appropriate usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim a GitHub issue by posting a comment expressing intent to work on it.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Custom claim message. If omitted, a default message is used. | |
| issueUrl | Yes | Full GitHub issue URL to claim |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only and not destructive. The description adds context that it posts a comment, which is a write operation. However, it does not disclose potential side effects like whether multiple claims are allowed or if it overrides existing claims.
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, clear sentence with no redundancy. Every word contributes to understanding the tool's purpose.
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 omits any mention of return values or error handling. Given the lack of an output schema, this information would help the agent interpret results. The tool is simple, but return behavior is not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema already provides adequate parameter descriptions. The tool description adds no further semantic value beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('claim'), the resource ('GitHub issue'), and the mechanism ('posting a comment expressing intent'). It effectively distinguishes from sibling tools like 'post' or 'startup' by specifying the intent-based claiming behavior.
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?
No explicit guidance on when to use this tool versus alternatives such as 'track' or 'post'. While the purpose implies usage for claiming, it does not mention prerequisites (e.g., needing a GitHub token) or scenarios to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch and display comments on a pull request, including review comments and issue comments.
| Name | Required | Description | Default |
|---|---|---|---|
| prUrl | Yes | Full GitHub PR URL to fetch comments for | |
| showBots | No | If true, include bot comments in the output |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, so the read-only nature is clear. The description adds that it includes both review and issue comments, providing some additional context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 17 words, front-loaded with key action and resource. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with 2 parameters and no output schema, the description adequately covers purpose and scope. Could mention return format but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for both parameters. The description does not add meaning beyond what the schema already provides, so baseline 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 action ('Fetch and display') and the resource ('comments on a pull request'), including specific types (review comments and issue comments). It distinguishes from siblings like 'post' which would create comments.
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?
No guidance on when to use this tool versus alternatives. The description does not mention when not to use it or suggest alternative tools for different contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get or set OSS Autopilot configuration values. With no args, shows all config. With key and value, sets the value.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Configuration key to get or set (e.g. "languages", "username") | |
| value | No | Value to set for the given key. Omit to read the current value. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only and idempotent. The description confirms mutability and adds the behavior with no args. It does not contradict annotations. However, it lacks details on persistence or side effects, relying on annotations for baseline.
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 sentences with no fluff. The description is front-loaded with action verbs and clearly separates the two modes. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional parameters and no output schema, the description covers essential behavior across parameter combinations. It does not describe output format or errors, but these are less critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters with descriptions. The description adds context by tying parameters to use cases: key for identification, value for setting, omit for reading. This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's dual purpose of getting or setting configuration values, and specifies behavior based on arguments (no args shows all, key+value sets). This uniquely identifies it 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 provides clear usage context for viewing or modifying configuration, with distinct behavior based on parameter presence. It does not explicitly exclude scenarios or name alternatives, but the context is adequate for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run daily PR monitoring check. Fetches all open PRs, enriches with CI status, reviews, and conflicts, then returns a prioritized summary.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the main behavior (fetches, enriches, returns) but does not address the annotations: readOnlyHint=false suggests potential side effects, yet no writes are mentioned. The description should clarify if any state is modified (e.g., logging the check). Without that, there is ambiguity.
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 of 20 words that succinctly conveys the action and output. Every word is necessary; no redundancy. It is front-loaded with the tool's purpose.
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 parameterless tool with no output schema, the description adequately covers what the tool does. However, it could mention the output format (e.g., what the 'prioritized summary' looks like) or any prerequisites (e.g., authentication). Given the simplicity, it is nearly 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?
There are no parameters, so the schema coverage is 100% (empty). The description adds no parameter info, but given zero parameters, a baseline of 4 is appropriate. The tool effectively requires no input, which is clear.
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: performing a daily PR monitoring check. It specifies the actions (fetching open PRs, enriching with CI status, reviews, conflicts, and returning a prioritized summary), which is specific and well-scoped. The verb 'Run' and resource 'daily PR monitoring check' are distinct from sibling tools like 'check-setup' or 'status'.
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 usage context is implied by the name and description: it's meant for daily PR monitoring. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'status' for overall status, or 'search' for custom queries). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dismiss a GitHub issue so it no longer appears in notifications.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Full GitHub issue URL to dismiss |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context about the notification effect beyond annotations, which indicate mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). It does not contradict 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, front-loaded sentence that efficiently conveys the tool's purpose and effect with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description completely covers the tool's purpose and effect for a simple one-parameter tool, though it could briefly mention the existence of 'undismiss' for reversibility context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description adds no additional meaning beyond the schema's parameter description for 'url'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'dismiss', the resource 'GitHub issue', and the effect 'no longer appears in notifications', distinguishing it from siblings like 'undismiss'.
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 dismissing issues from notifications but does not explicitly state when to use vs alternatives like 'undismiss' or other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialize OSS Autopilot with a GitHub username. Creates the state file and sets up initial configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | Your GitHub username |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) already indicate a non-read, non-destructive write operation. Description adds that it creates a state file and config, consistent with annotations, but does not detail idempotency or 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?
Single sentence, front-loaded with key action and inputs, 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 init tool with one parameter and no output schema, the description covers the essentials: what it does, what it requires, and what it creates. Minor omission about re-running behavior.
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% and description repeats 'GitHub username' from schema, adding no further semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: initialize OSS Autopilot with a GitHub username, creating state file and config. It distinguishes from siblings by specifying initialization action, though not explicitly contrasting with 'setup'.
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?
Implied usage as a first-step tool, but there is no explicit guidance on when to use or when not to use, nor alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a PR between states: attention (need attention), waiting (waiting on maintainer), shelved (hidden), or auto (reset to computed status).
| Name | Required | Description | Default |
|---|---|---|---|
| prUrl | Yes | Full GitHub PR URL | |
| target | Yes | Target state for the PR |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-destructive mutation, and the description adds state-specific detail, but it does not clarify side effects (e.g., whether 'shelved' hides the PR) or other behavioral traits beyond the state list.
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 concise sentence that efficiently conveys the main purpose, though it could benefit from minor structuring for 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?
Given the tool's simplicity, no output schema, and parameters fully described, the description covers the essential functionality adequately, though it omits return behavior or error conditions.
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?
Both parameters are fully described in the schema; the description adds no additional meaning beyond what the schema already provides, meeting the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's action ('Move a PR between states') and lists the valid target states, distinguishing it from siblings like 'shelve' or 'claim'.
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 states what the tool does but does not provide explicit guidance on when to use it versus alternatives (e.g., 'shelve' for the shelved state) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a comment on a GitHub issue or pull request.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Full GitHub issue or PR URL to comment on | |
| message | Yes | The comment text to post |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's claim of 'post a comment' adds no new behavioral insight. No details are given about idempotency, error handling, authentication requirements, or side effects beyond the basic write operation.
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 with no extraneous words. It efficiently conveys the core purpose without wasting any text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description omits critical context: no mention of the return value (given no output schema), no note on success/failure behavior, and no hints about required permissions or rate limits. This leaves the agent with incomplete information for reliable 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% coverage of its two parameters (url and message) with descriptions. The tool description itself adds no additional parameter meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'post' and the resource ('comment on a GitHub issue or pull request'), making the tool's purpose unambiguous. However, it does not explicitly differentiate from sibling tools like 'claim' or 'dismiss', which also perform mutations but on different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It lacks any context about prerequisites, when not to use it, or which sibling tool might be more appropriate for related tasks (e.g., reading comments).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark PR notifications as read. Requires either prUrl or all to be specified.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | If true, mark all PRs as read | |
| prUrl | No | Full GitHub PR URL to mark as read. Omit to use --all instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, meaning the tool mutates state but is not destructive. The description confirms mutation by saying 'Mark as read' but adds little beyond that. No annotation contradiction is present.
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 consists of two short, focused sentences. The first sentence states the purpose, and the second adds a critical usage requirement. No extraneous information or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description is mostly complete. It explains the action and a key constraint. However, it does not describe the return value or side effects (e.g., whether notifications disappear). The complexity is low, so minor gaps are acceptable.
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 describes both parameters with detailed descriptions. The description adds the mutual exclusivity constraint ('Requires either prUrl or all'), which is not explicitly in the schema. This adds value but is marginal given the schema coverage is 100%.
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 action: 'Mark PR notifications as read.' It specifies the verb (mark as read) and resource (PR notifications), making the purpose unambiguous. However, it does not differentiate from sibling tools like 'dismiss' or 'claim', which might have overlapping effects.
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 includes a usage constraint: 'Requires either prUrl or all to be specified.' This provides a necessary precondition but offers no guidance on when to choose this tool over alternatives like 'dismiss' or 'shelve'. The sibling list is provided but not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GitHub for beginner-friendly open-source issues to contribute to. Returns issues matching configured languages and interests.
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of issues to return (default: 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds that it returns issues matching configured languages/interests, which is useful but vague. It does not detail side effects or limits beyond reading.
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 sentences, front-loaded with action and purpose, no unnecessary words. Efficient and clear.
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?
With one parameter and no output schema, the description minimally covers what the tool does. However, it lacks details on return format or how configuration works, which would be needed for full completeness.
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% for the single parameter 'maxResults', so the description's role is minimal. It does not add additional meaning beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it searches GitHub for beginner-friendly issues and returns results matching configured preferences. It provides a specific verb and resource, but does not explicitly differentiate from sibling tools like 'read' or 'claim'.
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 context for using the tool to find issues to contribute to, but lacks explicit guidance on when not to use it or alternatives among siblings. No exclusion criteria are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run OSS Autopilot setup to configure preferences like languages, interests, and contribution goals.
| Name | Required | Description | Default |
|---|---|---|---|
| set | No | Set preferences non-interactively as key=value pairs (e.g. ["languages=typescript,rust"]) | |
| reset | No | If true, reset all preferences to defaults before running setup |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate the tool is neither read-only nor destructive. The description confirms it configures preferences, implying mutation. However, it does not disclose specific side effects (e.g., whether existing settings are overwritten, if reset is required first) or the interactive nature when no 'set' parameter is provided.
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 concise sentence, efficiently conveying the core purpose. No redundant information is present, though it could benefit from listing common use cases or mentioning the two parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional parameters, no output schema), the description covers the basic functionality. However, it lacks information about return values, potential interactivity, and any required prior setup, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with clear parameter descriptions. The tool description adds no additional guidance beyond the schema, missing an opportunity to explain the 'set' format or interaction between 'reset' and 'set'. 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 action ('Run OSS Autopilot setup') and the resource ('preferences like languages, interests, and contribution goals'). It effectively communicates the tool's purpose among siblings such as 'check-setup' and 'config', though it does not explicitly differentiate from them.
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 a general purpose but lacks explicit guidance on when to use this tool versus alternatives like 'check-setup' or 'config'. There is no mention of prerequisites, typical scenarios, or exclusions, which limits the agent's ability to make a well-contextualized choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shelve a PR to temporarily hide it from daily checks and status reports without untracking it.
| Name | Required | Description | Default |
|---|---|---|---|
| prUrl | Yes | Full GitHub PR URL to shelve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only and non-destructive. The description adds behavioral clarity by explaining the temporary hiding effect and that tracking is preserved, providing context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. Every word 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 tool is simple with one parameter and no output schema. The description covers the core behavior, though it could hint at reversibility via 'unshelve' for completeness. Still adequate.
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% for the single parameter 'prUrl'. The description does not add additional parameter meaning beyond what the schema already provides, so it meets the baseline.
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 'Shelve' and resource 'PR', clearly stating the action: temporarily hide from daily checks and status reports without untracking. This distinguishes it from siblings like 'untrack' and 'unshelve'.
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 temporarily hiding a PR while keeping it tracked, but it does not explicitly state when to use versus alternatives like 'untrack' or 'dismiss'. No when-not scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run startup checks including GitHub auth verification, state file validation, and configuration status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no safety hints (readOnlyHint=false, destructiveHint=false). The description lacks disclosure of side effects, idempotency, or state changes. For a startup tool, it should clarify if it modifies any configuration or just checks.
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?
Single sentence, no wasted words, front-loaded with the verb 'Run' and clearly lists the checks.
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?
With no output schema and no behavioral annotations, the description is insufficient. It omits what the tool returns (e.g., success/failure), whether it's safe to run repeatedly, and any impact on system state. The listed checks are vague without further context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. Baseline for 0 parameters is 4. The description does not add parameter details, which is acceptable.
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 runs startup checks and lists three specific areas: GitHub auth verification, state file validation, and configuration status. It differentiates from siblings like 'check-setup' or 'setup' by being the comprehensive startup routine.
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?
Implied usage as the main startup sequence, but no explicit guidance on when to use this vs alternative tools (e.g., 'check-setup' for partial checks). No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show current PR tracking status including open PRs, shelved PRs, and dismissed issues.
| Name | Required | Description | Default |
|---|---|---|---|
| offline | No | If true, show only locally cached state without fetching from GitHub |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds moderate value by specifying the categories of status shown, but does not disclose any further behavioral nuances (e.g., caching behavior beyond the offline parameter, data freshness).
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 directly states the tool's purpose and key items. It is front-loaded and contains no filler, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only query tool with one optional parameter and no output schema, the description adequately conveys the purpose and scope. However, it could provide more detail on how the status is structured or returned, and it does not clarify how the offline parameter interacts with the described output.
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 covers the single boolean parameter 'offline' with a clear description. The tool-level description does not mention the parameter nor add meaning beyond the schema, so baseline 3 applies due to 100% schema coverage.
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 ('Show') and resource ('current PR tracking status'), and details the exact items included (open PRs, shelved PRs, dismissed issues). This clearly defines the tool's purpose and distinguishes it from sibling action tools like track or shelve.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as search, track, or shelve. It lacks explicit when-to-use, when-not-to-use, or comparison with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start tracking a pull request. Adds the PR to your monitored list so it appears in daily checks and status reports.
| Name | Required | Description | Default |
|---|---|---|---|
| prUrl | Yes | Full GitHub PR URL to track (e.g. https://github.com/owner/repo/pull/123) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readonly (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds context that the tool mutates state by adding to a monitored list and affects daily checks, which is helpful 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?
Two sentences, no redundant words, front-loaded with the action. Every word serves a purpose.
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 tracking tool with one parameter and no output schema, the description covers essential behavior. It mentions the effect on daily checks and status reports, though it could optionally note return value or confirmation.
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% with a clear description for prUrl, including an example. The tool description does not reiterate or enhance parameter meaning, 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: 'Start tracking a pull request. Adds the PR to your monitored list...' It uses a specific verb-resource pair ('track' + 'pull request') and distinguishes from sibling 'untrack' which removes tracking.
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 (when you want to monitor a PR for daily checks) without explicit alternatives or exclusions. Sibling tools like 'untrack' provide contrast, but no direct comparison is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Undismiss a previously dismissed issue, re-enabling notifications.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Full GitHub issue URL to undismiss |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-destructive and non-readonly behavior. The description adds the effect of re-enabling notifications, which is useful but does not disclose prerequisites or side effects beyond that.
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?
One clear, front-loaded sentence with no wasted words. Appropriate length for a simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter with full schema coverage, no output schema, and annotations present, the description is complete enough for an AI to correctly select and invoke the 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?
The input schema fully describes the single parameter 'url' with 100% coverage, so the description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'undismiss', the resource 'issue', and the effect 're-enabling notifications'. This effectively distinguishes from its sibling 'dismiss'.
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 use only for previously dismissed issues, but does not explicitly state when to use or when not, nor mention alternatives like 'unshelve' or 'vet'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unshelve a previously shelved PR, returning it to active monitoring.
| Name | Required | Description | Default |
|---|---|---|---|
| prUrl | Yes | Full GitHub PR URL to unshelve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive behavior. The description adds context about returning to active monitoring but does not disclose prerequisites, side effects, or error conditions.
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, concise sentence with no wasted words. It is front-loaded with the verb and efficiently conveys the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the core functionality and outcome. It lacks detail on preconditions but is largely adequate.
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% with a clear parameter description. The tool description adds minimal extra meaning beyond the schema, simply rephrasing the parameter's purpose.
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 'unshelve' and resource 'PR', clearly stating the action of returning it to active monitoring. It effectively differentiates from sibling tools like 'shelve'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a PR is shelved and needs reactivation, providing clear context. However, it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop tracking a pull request. Removes the PR from your monitored list.
| Name | Required | Description | Default |
|---|---|---|---|
| prUrl | Yes | Full GitHub PR URL to untrack (e.g. https://github.com/owner/repo/pull/123) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description merely confirms the removal action without adding new behavioral context. No contradiction, but no extra info beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences that front-load the purpose with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, clear annotations, no output schema), the description fully communicates what is needed for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a well-described parameter (prUrl). The tool description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Stop tracking' / 'Removes') and the resource ('pull request from your monitored list'), which distinguishes it from sibling tools like 'track'.
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 implicitly indicates when to use the tool (when you want to stop tracking a PR), but provides no explicit guidance on alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze a GitHub issue to determine if it is a good candidate for contribution. Checks for clarity, scope, existing assignees, and staleness.
| Name | Required | Description | Default |
|---|---|---|---|
| issueUrl | Yes | Full GitHub issue URL to vet (e.g. https://github.com/owner/repo/issues/123) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the tool is non-destructive. The description adds behavioral details about what it checks (clarity, scope, assignees, staleness), providing useful context beyond the annotation. No contradiction.
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 efficient sentences: first states the primary purpose, second lists specific checks. No redundant words, front-loaded with key action.
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 adequately explains the tool's function and checks. However, it does not hint at the output format (e.g., boolean or detailed report), which would enhance completeness. Nonetheless, for a simple assessment tool, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter issueUrl is fully described in the input schema with a clear format and example. The tool description adds no additional semantic information about the parameter beyond what the schema provides, achieving baseline for high schema coverage.
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 'Analyze' and the resource 'a GitHub issue', with a specific purpose 'to determine if it is a good candidate for contribution'. It also enumerates the checks performed (clarity, scope, assignees, staleness), making it distinct from sibling tools like 'read' or 'claim'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool: to vet an issue for contribution. While it doesn't explicitly state when not to use it, the sibling tool names provide context (e.g., 'claim', 'read'), and the description implies it is for assessment, not action.
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.
v3.0.16dailystatusv3.0.15dailystatusScored across 20 tools
Most tools are distinct, but several clusters overlap: init/setup/config/check-setup/startup all concern configuration, and move overlaps with shelve/unshelve by supporting a shelved state. Descriptions clarify intent, but an agent could easily select the wrong tool in these areas.
The set uses a consistent lowercase command style with clear un- reversals (untrack, unshelve, undismiss). A few names are nouns or adjectives (status, comments, daily, startup) and check-setup is hyphenated, but the overall pattern is readable and predictable.
At 20 tools, the server is on the heavy side for its scope. The count is justifiable given PR tracking, issue triage, state management, and setup clusters, but some tools (check-setup/startup, shelve/unshelve vs move) could be consolidated.
The core workflow is covered: discover issues, vet them, claim/comment, track PRs, run daily checks, and manage state via shelve/dismiss/move. Minor gaps exist such as no explicit reset/uninitialize and no dedicated single-PR detail fetch, but agents can work around these.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
A Model Context Protocol (MCP) application for automated GitHub PR analysis and issue management.…
Package intelligence MCP for AI agents — 22 tools, 19 ecosystems, AGPL SDK, free.
Repo intel for AI coding agents: overview, PRs, contributors, hot files, CI, deps. Remote MCP.
