Allows interaction with Jira issues: retrieve issue details, download attachments, and add comments.
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., "@hive-mcp get issue ABC-123 details"
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.
A Model Context Protocol (MCP) server that provides integrations for Jira and Sourcegraph. This allows LLMs to interact with Jira issues and search code across repositories using Sourcegraph.
Package name: hive-mcp
Tool prefix: Service name (e.g., jira_*, sourcegraph_*)
Full tool names in LLM: mcp__hive-mcp__jira_get_issue etc.
Get Issue: Retrieve detailed information about Jira issues
Download Attachments: Download attachments from Jira issues
Add Comments: Post comments to Jira issues
Code Search: Search code across repositories with powerful query operators (GraphQL)
Deep Search: AI-powered conversational code search that understands natural language questions (REST API v6.7+)
Related MCP server: Jira MCP Server
Node.js 18 or higher
Jira Server/Data Center instance with API access
Sourcegraph instance with API access
GitHub account with access to the @ocuco organization
This package is published as a private package on GitHub Packages. To install it, you need to authenticate with GitHub first.
Go to GitHub Settings > Developer Settings > Personal Access Tokens > Tokens (classic)
Click "Generate new token" > "Generate new token (classic)"
Give it a descriptive name (e.g., "NPM Package Access")
Select the following scopes:
read:packages - Download packages from GitHub Package Registry
write:packages - Upload packages to GitHub Package Registry (only needed for publishing)
Click "Generate token" and copy the token
Create or edit your ~/.npmrc file (in your home directory) and add:
@ocuco:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKENReplace YOUR_GITHUB_TOKEN with the token you created in step 1.
Note: On Windows, your home directory is %USERPROFILE% (usually C:\Users\YourUsername)
npm install -g @ocuco/hive-mcpgit clone https://github.com/ocuco/hive-mcp.git
cd hive-mcp
npm install
npm run build
npm linkCreate a .env file in your project root or set environment variables:
# Jira Configuration (On-Premise Server/Data Center)
JIRA_BASE_URL=https://jira.your-company.com
JIRA_API_TOKEN=your_personal_access_token
# Sourcegraph Configuration
SOURCEGRAPH_URL=https://sourcegraph.company.com
SOURCEGRAPH_TOKEN=your_sourcegraph_tokenFor Jira Server/Data Center on-premise installations:
Log in to your Jira instance
Navigate to your Profile → Personal Access Tokens
Click Create token
Give it a name (e.g., "MCP Server Access")
Set expiration date (optional, recommended for security)
Click Create and copy the token
Use this token as JIRA_API_TOKEN
Important Notes:
Personal Access Tokens are available in Jira 8.14 and later
For older versions, contact your Jira administrator for API access options
Keep your token secure and never commit it to version control
The token is used with Bearer authentication
Self-signed SSL certificates are automatically handled
Go to your Sourcegraph instance
Navigate to Settings > Access tokens
Create a new access token
Copy the token and use it as SOURCEGRAPH_TOKEN
Add to your Claude Desktop configuration file:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"hive-mcp": {
"command": "node",
"args": ["/path/to/hive-mcp/dist/index.js"],
"env": {
"JIRA_BASE_URL": "https://jira.your-company.com",
"JIRA_API_TOKEN": "your_personal_access_token",
"SOURCEGRAPH_URL": "https://sourcegraph.company.com",
"SOURCEGRAPH_TOKEN": "your_sourcegraph_token"
}
}
}
}Or if installed globally from GitHub Packages:
{
"mcpServers": {
"hive-mcp": {
"command": "hive-mcp",
"env": {
"JIRA_BASE_URL": "https://jira.your-company.com",
"JIRA_API_TOKEN": "your_personal_access_token",
"SOURCEGRAPH_URL": "https://sourcegraph.company.com",
"SOURCEGRAPH_TOKEN": "your_sourcegraph_token"
}
}
}
}Note: After installing from GitHub Packages with npm install -g @ocuco/hive-mcp, the command name remains hive-mcp (defined in package.json bin field).
All tools are prefixed with their service name for easy identification in LLM tool lists.
Full name format in LLM: mcp__hive-mcp__<tool_name>
jira_get_issueGet detailed information about a Jira issue.
Parameters:
issueIdOrKey (string): The issue key (e.g., "PROJ-123") or ID
Example:
{
"issueIdOrKey": "PROJ-123"
}jira_get_commentsGet all comments from a Jira issue. Returns comment history with authors and timestamps.
Parameters:
issueIdOrKey (string): The issue key (e.g., "PROJ-123") or ID
Returns:
Total comment count
Array of comments with:
Author name and email
Created and updated timestamps
Comment body (Atlassian Document Format)
Example:
{
"issueIdOrKey": "PROJ-123"
}jira_add_commentAdd a comment to a Jira issue.
Parameters:
issueIdOrKey (string): The issue key (e.g., "PROJ-123") or ID
comment (string): The comment text to add
sourcegraph_search_codeSearch code across repositories.
Parameters:
query (string): Search query with optional operators
repo:owner/name - Filter by repository
file:path - Filter by file path
lang:python - Filter by language
And more...
Example:
{
"query": "function handleRequest repo:myorg/myrepo lang:typescript"
}sourcegraph_deep_searchAI-powered Deep Search using natural language questions. This feature creates a conversation with Sourcegraph's AI agent (requires v6.7+).
Parameters:
question (string): Natural language question about your codebase
timeout_seconds (number, optional): Max wait time for answer (default: 60)
Example:
{
"question": "How does authentication work in this codebase?"
}Response includes:
AI-generated answer
Relevant source code references
Suggested follow-up questions
Conversation ID for follow-ups
Shareable URL
Note: Deep Search is async and may take 10-60 seconds. It uses credits/quota on Sourcegraph Enterprise.
MCP Resources allow LLMs to read Jira attachments like local files. The server handles caching and download automatically.
Resource URI Format:
jira://issues/{issueKey}/attachmentsList all attachments for a specific Jira issue.
Example:
jira://issues/PROJ-123/attachmentsReturns:
List of all attachments with metadata
Each attachment includes its resource URI for direct access
jira://attachments/{attachmentId}Read specific attachment content.
Example:
jira://attachments/10041Behavior:
Images <500KB: Returns image blob (viewable directly)
Files <500KB: Returns base64 content
Files >500KB: Returns metadata + warning
Automatic caching: Small files cached for 5 minutes
Advantages:
✅ LLM reads attachments like local files
✅ No repeated downloads (smart caching)
✅ No authentication errors (handled by MCP)
✅ Automatic size management
Usage in Claude:
"Read jira://attachments/10041"
"Show me all attachments from PROJ-123"# Install dependencies
npm install
# Build
npm run build
# Development mode (watch for changes)
npm run dev
# Run the server
npm startNote: Only maintainers with write access to the @ocuco organization can publish.
Create a GitHub Personal Access Token with write:packages scope (see Installation section)
Ensure your local ~/.npmrc has the authentication configured
Make sure you're logged in to npm: npm whoami --registry=https://npm.pkg.github.com
Update version (choose one):
npm version patch # 1.0.0 -> 1.0.1
npm version minor # 1.0.0 -> 1.1.0
npm version major # 1.0.0 -> 2.0.0Build the project:
npm run buildPublish to GitHub Packages:
npm publishPush changes and tags:
git push
git push --tagsThe package is set as private ("access": "restricted" in publishConfig). Only members of the @ocuco organization with proper permissions can:
View the package
Download and install the package
Publish new versions (with write access)
To manage package access:
Go to the package page on GitHub
Find the hive-mcp package
Go to "Package settings" > "Manage Actions access" to configure permissions
hive-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── config.ts # Environment configuration
│ ├── types.ts # Shared types
│ ├── jira/
│ │ ├── client.ts # Jira REST API client
│ │ ├── tools.ts # Jira MCP tools
│ │ └── types.ts # Jira types
│ └── sourcegraph/
│ ├── client.ts # Sourcegraph GraphQL client
│ ├── tools.ts # Sourcegraph MCP tools
│ └── types.ts # Sourcegraph types
└── dist/ # Compiled outputMIT
Contributions are welcome! Please feel free to submit a Pull Request.
Add a comment to a Jira issue
| Name | Required | Description | Default |
|---|---|---|---|
| comment | Yes | The comment text to add | |
| issueIdOrKey | Yes | The issue key (e.g., PROJ-123) or ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral expectations. It only states the action without mentioning permissions, whether it appends to existing comments, what response to expect, or any side effects, leaving a significant transparency gap.
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 gets straight to the point with no redundant or 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?
The tool is relatively simple with two well-documented parameters, but the lack of annotations and output schema means the description should provide more context about behavior and return values. It is minimally adequate for a simple add-comment operation without being fully comprehensive.
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 with clear descriptions for both parameters (comment text and issue key/ID). The description adds no additional parameter context beyond what the schema already provides, meeting the 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 uses a specific verb ('Add') and resource ('comment to a Jira issue'), clearly distinguishing it from sibling tools like jira_get_comments which retrieves comments, and jira_get_issue which fetches issue details.
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 states the tool's purpose, making its primary use case obvious. However, it does not explicitly mention when to avoid this tool or use an alternative, relying on the sibling tool names to imply differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comments from a Jira issue with pagination support. Returns comment history with authors, timestamps, and content. Use pagination parameters to control response size and avoid token limits.
| Name | Required | Description | Default |
|---|---|---|---|
| startAt | No | The index of the first comment to return (0-indexed). Default: 0 | |
| maxResults | No | Maximum number of comments to return per request (max: 100). Default: 5 | |
| issueIdOrKey | Yes | The issue key (e.g., PROJ-123) or ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It does explain that the tool returns authors, timestamps, and content, and hints at potentially large responses via pagination advice. However, it does not disclose sorting order, error behavior, or permission requirements, which would be helpful for a full understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each with a clear purpose: stating the primary function, describing the returned data, and offering usage guidance. There is no fluff or redundancy, and the most important information is front-loaded.
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 tool with no output schema, the description adequately covers the purpose, return content, and pagination support. It lacks specifics about pagination response structure (e.g., total count) but overall provides enough context for an agent to understand and use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description only adds a general note that pagination parameters control response size, reinforcing what the schema already states. It does not provide additional meaning or context beyond the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Get comments from a Jira issue', clearly specifying the action and resource. It distinguishes from sibling tools like jira_add_comment (write) and jira_get_issue (issue details) by focusing on reading comment history. Also mentions pagination support and return contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose makes clear when to use this tool: when needing comment history for an issue. It also advises using pagination parameters to control response size and avoid token limits, which is practical guidance. However, it doesn't explicitly state when not to use it or compare with alternatives like jira_add_comment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a Jira issue by its key or ID (e.g., PROJ-123). IMPORTANT: Use the fields parameter to control response size and avoid token limits. Default fields provide essential info (summary, status, priority, assignee, reporter, created, updated, issuetype) without bloating response.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Optional array of specific field names to fetch. Omit this parameter to use default minimal fields (recommended: summary, status, priority, assignee, reporter, created, updated, issuetype). Only specify fields if you need additional information. For comments use jira_get_comments tool, for attachments use jira_list_attachments tool. Common fields: description, labels, components, fixVersions, resolution, resolutiondate, duedate, environment, customfield_* | |
| issueIdOrKey | Yes | The issue key (e.g., PROJ-123) or ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals that the default response includes a minimal set of fields to avoid token limits, which is a significant behavioral trait. However, it does not mention error handling, authentication, or response shape beyond field listings, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loading the core purpose and then providing essential usage tips. Every sentence contributes value: the first identifies the resource, the second and third explain parameter usage and default behavior. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with only two parameters and no output schema, the description plus schema cover the essential aspects: how to identify the issue, what default fields are returned, how to customize fields, and which sibling tools to use for related operations. Error handling and auth are not explicitly covered, but these are commonly inferred and not critical for a basic retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% since both parameters have detailed descriptions in the schema. The description adds a note about using 'fields' to control response size, but this duplicates information already present in the schema description. With high schema coverage, the baseline of 3 is appropriate; the description does not enrich parameter 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 'Get detailed information about a Jira issue by its key or ID', which is a specific verb+resource combination. The tool's purpose is unambiguous and inherently distinct from sibling tools like jira_get_comments and jira_list_attachments, especially since the schema explicitly mentions these alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The schema explicitly directs users to jira_get_comments for comments and jira_list_attachments for attachments, providing clear alternative tool guidance. Additionally, the description advises using the fields parameter to control response size and indicates when to add fields ('Only specify fields if you need additional information'), effectively stating when to use this tool's features versus defaults.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all attachments for a Jira issue. Returns attachment metadata including IDs, filenames, sizes, and mime types.
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The issue key (e.g., PROJ-123) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It discloses that the tool returns metadata (IDs, filenames, sizes, mime types) and implicitly indicates it is a read-only list operation. It does not mention edge cases like pagination or empty results, but for a simple listing tool this is sufficient.
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 concise sentences with no wasted words. The first sentence states the core purpose, and the second clarifies the return value, making it optimally front-loaded.
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?
This is a low-complexity tool with a single parameter and no output schema. The description adequately covers the tool's purpose and return value, though it could mention potential limitations (e.g., whether attachments are paginated) to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter (issueKey) with an example format. The description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies the exact resource ('attachments for a Jira issue'), clearly distinguishing it from sibling tools like jira_read_attachment (which implies reading content) and jira_get_comments. It also names the output type (metadata) and key fields.
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 (to list attachments and get their metadata) but provides no explicit guidance on when to prefer this over jira_read_attachment or other siblings. It does not state exclusions or alternatives, though the verb 'List' helps infer scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a specific Jira attachment by ID. Returns the attachment content (images as blob, other files as base64). Files larger than 500KB will return metadata only.
| Name | Required | Description | Default |
|---|---|---|---|
| attachmentId | Yes | The attachment ID (e.g., 10041) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses non-obvious behaviors: images return as blob, other files as base64, and files over 500KB return only metadata. This gives the agent clear expectations about output variations, though it omits error handling and authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the purpose. Every sentence contributes: purpose, return format, and size threshold. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with no output schema, the description covers the essential aspects: action, return format, and size limit. It lacks explicit error-case handling, but the tool is simple enough that the description is sufficiently complete for an agent to select and invoke 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?
The input schema already provides a description for attachmentId with an example, achieving 100% coverage. The description's 'by ID' adds no new semantic meaning beyond the schema, so it stays at the 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 opens with a specific verb and resource: 'Read a specific Jira attachment by ID.' This clearly identifies the action and target. It also distinguishes itself from sibling jira_list_attachments by focusing on reading a single attachment's content rather than listing.
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 an attachment ID is known and content is needed, but it does not explicitly contrast with alternatives like jira_list_attachments or state when not to use this tool. The size-limit note provides some contextual boundary, but not a direct usage guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI-powered Deep Search that understands natural language questions about your codebase. Ask questions like "How does authentication work?" or "Where are API endpoints defined?". This uses Sourcegraph's agentic search (REST API v6.7+) and may take 10-60 seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | Natural language question about your codebase. Examples: "Does the repo have a README?", "How is error handling implemented?", "Where are database migrations defined?" | |
| timeout_seconds | No | Optional: Maximum time to wait for answer (default: 60 seconds) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden. It discloses that it uses Sourcegraph's agentic search (REST API v6.7+) and may take 10-60 seconds, which is useful. However, it does not explicitly state that it is a read-only operation or describe any side effects, which is a gap for a tool with no annotation coverage.
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: the first gives the primary purpose with examples, the second adds key technical details about the underlying API and latency. It is front-loaded, concise, and every sentence adds value without 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 tool has no output schema, so the description should explain what the tool returns. It does not describe the output format or content of the answer. It covers the key operational context (time, API) but misses return value expectations and any caveats about scope or limitations.
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, so the baseline is 3. The description reinforces the question parameter with examples, but it does not add new meaning beyond what the schema already provides. The timeout_seconds parameter is not mentioned in the description but is fully covered by 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 this is an AI-powered deep search for natural language questions about a codebase, with concrete examples. It distinguishes itself from sibling sourcegraph_search_code by emphasizing natural language and agentic search, and from other Jira tools which are unrelated.
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 by giving example questions and noting it may take 10-60 seconds. However, it does not explicitly mention when to use sourcegraph_search_code instead of this tool, though the natural language focus implies it for conversational queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search code across repositories using Sourcegraph. Supports various search operators like repo:, file:, lang:, count:, patterntype:, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query. Can include operators like "repo:owner/name", "file:path", "lang:python", "count:50", "patterntype:literal" (default), "patterntype:regexp", or "patterntype:structural". Examples: "payment count:50", "function handleRequest repo:myorg/myrepo", "func.*Handler patterntype:regexp" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only states that it searches code and supports operators, but does not disclose potential side effects, rate limits, authentication requirements, or limitations such as result caps or default patterns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences long, and front-loaded with the primary purpose. There is no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with a rich schema, the description covers the core purpose and operator support. However, it lacks behavioral context (e.g., limitations) and does not guide the user toward or away from the sibling tool, making it incomplete for a tool in a contextual set.
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 description for the query parameter is very detailed, listing operators and examples. The tool description adds only a general mention of operators, which does not exceed what the schema already provides. With 100% 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 clearly states the tool's function: 'Search code across repositories using Sourcegraph.' This is a specific verb and resource. However, it does not distinguish it from the sibling tool sourcegraph_deep_search, so it doesn't fully differentiate.
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 use this tool versus the sibling sourcegraph_deep_search. The description mentions supported operators but does not provide context for selecting this tool over alternatives, such as when a deep search is needed.
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.
v1.0.0jira_add_commentjira_get_commentsjira_get_issuejira_list_attachmentsjira_read_attachmentsourcegraph_deep_searchsourcegraph_search_codeScored across 7 tools
The Jira and Sourcegraph tools are cleanly separated by prefix and purpose. Each Jira tool targets a distinct resource (issue, comments, attachments), and the two Sourcegraph tools are clearly differentiated by search mode.
All tool names follow a consistent snake_case pattern with a service prefix (jira_ or sourcegraph_) followed by a clear verb_noun structure (e.g., get_issue, add_comment, search_code). No mixed conventions.
The 7-tool count is within the ideal range, but the server spans two distinct domains (Jira and Sourcegraph), which slightly dilutes focus. Still, each tool earns its place for basic workflows.
The Jira coverage lacks core operations like create_issue, update_issue, or delete_issue, limiting workflow completion. Sourcegraph only offers search and deep search, with no direct file retrieval or repository browsing, leaving notable gaps for a development tool.
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Plan Salesforce deploys, open pull requests and trigger pipelines from your AI client.
