gitea-mcp
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation5/5
Each tool targets a distinct resource or action, with clear documentation differentiating similar tools like add_comment and add_comment_on_pr. No overlapping purposes that would cause agent misselection.
Naming Consistency5/5All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_branch, list_issues, merge_pr). The pattern is predictable and uniform across the entire set.
Tool Count4/5With 21 tools, the count is slightly above the ideal 3-15 range but justified by the broad domain of Gitea repository management. The tools cover a comprehensive set of operations without being excessive.
Completeness3/5The tool surface covers core CRUD for issues and PRs but has notable gaps: no update for PRs, no delete operations for any resource, and no management tools for labels or milestones. Some gaps are acknowledged as out of scope, but the set is not fully comprehensive.
Average 4.2/5 across 21 of 21 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that it returns the created Comment object, but does not disclose potential side effects, authorization needs, or rate limits. Adequate but minimal extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, directly conveying purpose and return value. Maximum conciseness for the information provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema (not detailed but implied), the description covers the core action and return. It could mention the expected format of the Comment object, but overall is complete for this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description provides no additional meaning beyond the parameter descriptions. Baseline score of 3 is appropriate as the schema already documents parameters sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a comment') and resource ('to an existing issue'), and mentions the return value. It could explicitly differentiate from the sibling tool 'add_comment_on_pr', but the name and context suffice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like 'add_comment_on_pr', nor prerequisites such as issue existence or required permissions. The description lacks any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint: true and openWorldHint: true, so the description adds no new behavioral traits beyond confirming it's a read operation. No contradictions, but minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 9 words with no wasted text. It efficiently conveys the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the main action and filter, it does not mention pagination parameters (page/limit) or that results are paginated. Given the output schema exists and annotations provide safety context, the description is minimally adequate but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a description. The description adds the context of optional state filtering, but parameter meanings are already clear from the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (milestones in a repository), and the resource name distinguishes it from siblings like list_branches or list_issues. However, it could be more specific about scope, e.g., 'list milestones for a given repository'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing milestones, and the optional state filter is noted. However, no explicit guidance is given on when to use this tool versus alternatives (e.g., other list tools), but the sibling tools are for different entities, so context is somewhat clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key side effect beyond annotations: tag creation occurs even for drafts if the tag does not exist. Annotations already indicate non-read-only, but this adds specific behavioral context. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with one main sentence and a warning block. Every sentence adds value, and it is front-loaded with the core purpose. Slightly verbose due to the warning, but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (8 parameters, 4 required), the description covers the primary action and important side effects. An output schema exists, so return value details are not needed. The description is sufficient for an agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description's warning re-emphasizes tag_name and target_commitish behavior already detailed in the schema, adding no new semantics beyond the existing parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a new release in a repository' with a specific verb and resource. No sibling tool performs the same action, so it is clearly distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. However, since it is the only release creation tool, usage is implied. No exclusion criteria or when-not-to-use context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint and destructiveHint. Description adds value by stating return of Branch object and clean failure on duplicate branch name, which annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first states purpose, second adds return and error info. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description need not detail return. Error behavior is covered. Could mention prerequisites like write access, but overall adequate for a creation tool with well-documented schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so schema already documents all parameters. Description adds minimal extra meaning beyond confirming the error condition for new_branch_name. No elaboration on old_branch_name or usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create a new branch in a repository.' with specific verb-resource combo. Distinguishes from sibling list_branches by describing creation and return of a Gitea Branch object.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for creating branches, but does not explicitly state when to use vs. alternatives like list_branches or merge_pr. No when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and openWorldHint. The description adds that only true issues are returned (excluding PRs) and that filters compose (state AND labels AND assignee). This provides useful behavioral details 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, no filler, and front-loaded with the core purpose. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It covers the key behavioral aspects (exclusion of PRs, filter logic) and is sufficient for a list tool with clear input schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 does not add any additional parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists issues in a Gitea repository, explicitly excluding pull requests. This distinguishes it from sibling tools like list_pull_requests and get_issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that filters compose with AND logic but does not provide explicit guidance on when to use this tool versus alternatives (e.g., get_issue for a single issue or list_pull_requests for PRs). Usage context is implied but not directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-destructive write with open-world side effects. The description adds endpoint details and infrastructure sharing but does not mention specific side effects like notifications or prerequisites, which with existing annotations is moderately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main purpose, and efficiently includes both high-level and technical details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and full parameter descriptions, the description adequately covers the tool's scope, limitations, and context of use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters. The description does not add extra meaning, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a comment to a pull request's discussion thread,' specifying the verb and resource. It distinguishes from sibling tools by noting that inline diff-line review comments require a separate tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool for PR discussion threads and explicitly excludes inline diff-line review comments. It provides context about the shared endpoint but does not directly compare to the sibling 'add_comment' tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, covering basic behavioral aspects. The description adds a note about return values and downstream usage, but doesn't disclose additional behaviors like pagination behavior or rate limits. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two sentences that front-load the main purpose and then add a useful usage hint. Every sentence serves a purpose with no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of an output schema, and annotations covering read-only and open-world hints, the description provides sufficient context. It explains the return object and how to use the output, making it complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so the description doesn't need to elaborate on parameters. It adds a hint about using label IDs, which is beneficial but not directly about this tool's parameters. Thus, the description meets the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'labels defined in a repository', leaving no ambiguity about the tool's function. It also specifies the return object type, reinforcing the purpose. Since there are no sibling tools for labels, differentiation is inherent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on how to use the output (label IDs) in other tools that accept label_ids, and clarifies that most tools accept label names. It doesn't explicitly state when to use this tool vs alternatives, but given it's the only label-listing tool, this is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true and openWorldHint true, so the description adds value by specifying that results include drafts and pre-releases and are sorted newest first. This is helpful context 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second adds key behavioral details. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description adequately covers the tool's behavior (includes drafts, pre-releases, sort order). Complements the structured fields well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and descriptions are clear. The tool description does not add any additional parameter-specific guidance, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List releases') and resource ('for a repository'). It distinguishes itself from sibling tools like create_release (different action) and list_repos (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage context (listing releases) but does not explicitly discuss when to use this tool over alternatives or exclude certain scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that the tool is tagged destructiveHint=True because it changes repository history and closes the pull request. This adds behavioral context beyond what the annotations already provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, front-loaded with the core action, and no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description is complete: it covers the endpoint, destructive nature, parameter behavior, and closes the pull request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description only briefly mentions merge strategy and optional commit-message overrides, adding little meaning beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Merge a pull request' and explains it calls the GitHub API endpoint. This distinguishes it from sibling tools like create_pr or add_comment_on_pr.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions using merge strategies and optional commit-message overrides but does not provide explicit guidance on when to use this tool versus alternatives, such as when to rebase or squash. Usage is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a write operation (readOnlyHint=false) and non-destructive nature. The description adds value by detailing the return of the full Issue object (number, URL, metadata) and the label resolution behavior, including clean failure with valid names. This goes beyond annotations but could also mention potential side effects (e.g., notifications) hinted by openWorldHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a third explaining label behavior. No wasted words, essential information front-loaded with purpose, then return details, then parameter-specific nuance. Ideal for quick agent comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, an output schema, and sibling tools, the description is mostly complete. It covers creation, return value, and label resolution. However, it does not mention that owner and repo must exist, or that assignees must be valid users (though schema infers this). The openWorldHint suggests side effects like notifications, which are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 7 parameters. The description adds meaning beyond the schema by explaining label name resolution to IDs and the error behavior on unknown labels. It also clarifies the return value structure including number, URL, and metadata.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new issue in a Gitea repository.' This is a specific verb-resource pair that differentiates it from sibling tools like update_issue (modify) or get_issue (read).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It provides no guidance on use cases, prerequisites, or when to prefer other tools like add_comment or list_issues. The purpose is clear, but usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that the returned objects are Gitea PullRequest objects with richer information, which adds behavioral context beyond the readOnlyHint and openWorldHint annotations. It does not contradict annotations (readOnlyHint=true indicates read-only, description says list). The pagination behavior is left to schema, but the return type difference is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no unnecessary words. The first sentence states the core purpose, and the second adds a critical distinction. Every sentence earns its place, and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (not shown) and schema coverage is 100%, the description is nearly complete. It addresses the return type difference and optional filtering, though it could mention default sort order or pagination behavior more explicitly. Still, it adequately covers the tool's context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema coverage is 100%, the description does not need to repeat parameter details. It adds value by explaining the return type difference, which is related to the overall behavior rather than individual parameters. Baseline 3 is appropriate as the description provides some additional context but not per-parameter enrichment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List pull requests in a repository' with an optional filter parameter, distinguishing it from siblings like get_pull_request (single PR) and list_issues (which returns different objects). The added note about Gitea PullRequest objects versus Issue-style provides a specific differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that when richer head/base/mergeable info is needed, this tool is preferable over list_issues with type=pulls. However, it does not explicitly state when not to use it or compare to get_pull_request. It provides clear context for when to use this endpoint over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false (write), destructiveHint=false, openWorldHint=true. The description adds concrete error conditions and the return object, but does not contradict annotations. It could disclose more about side effects like triggering CI, but the openWorldHint already implies external effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose, followed by return value and error conditions. No extraneous information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, 5 required, output schema present), the description sufficiently covers return values and error handling. It does not need to repeat output schema details or annotations, and the context is complete for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal extra info, e.g., noting same-repo only for head and Markdown format for body, but does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Open a new pull request from head into base,' specifying the action (open) and resource (pull request). It differentiates from sibling tools like merge_pr and list_pull_requests, and explicitly mentions same-repo only, distinguishing from potential cross-fork PR creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool's purpose and lists error conditions (head branch doesn't exist, no commits, existing open PR) that indicate when not to use it. It does not explicitly mention alternatives among siblings, but the context of sibling tools makes it clear that this is the only PR creation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the returned object includes a 'comments_list' field beyond the standard payload, and preserves the 'comments' count. This adds value beyond the readOnlyHint and openWorldHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second provides key behavioral detail. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the description's explanation of the extra field, the tool is fully documented for an agent to understand inputs and outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description does not add additional detail beyond what is in the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get a single issue by number, including all of its comments', which uses a specific verb and resource. It clearly distinguishes from sibling tools like list_issues and update_issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when retrieving a single issue by number but does not explicitly state when not to use it or suggest alternatives like get_pull_request for PRs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and openWorldHint. The description adds the return format (array with specific fields) and usage context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the action, second explains the return structure and use cases. No wasted words, information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 4 parameters (2 required) and an output schema, the description covers purpose, usage, and output format. Annotations supplement safety. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (4 params fully described). The description adds no additional parameter details beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Tool name and description clearly state 'List branches in a repository.' It specifies the return type (Branch object array) and provides concrete use cases: inspecting before creating a release, opening a PR, or filing a fix. This differentiates it from sibling tools like create_branch or create_pr.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly mentions when to use the tool: inspecting available targets before actions. While it doesn't list exclusions, the context is clear and the sibling tool names provide implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds valuable behavioral details: the return shape includes a decoded 'text' field (None for binary), preserved base64 content and encoding, and the sha field's role in updates. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then efficient explanation of output fields and sha relevance. No redundant information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main aspects: reading content, binary handling, output fields, and the sha relationship. However, it lacks mention of error conditions (e.g., file not found, permissions) or size limits, which would be helpful given an output schema exists but is not shown. Still generally complete for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema itself documents all parameters. The description does not add extra meaning beyond what the schema provides, such as the ref parameter's default behavior (which is already in the schema's description). Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Read a file's content from a Gitea repository.' This specific verb+resource description distinguishes it from sibling write-oriented tools like commit_changes or add_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context about the sha field's relationship to commit_changes, advising that callers usually don't need to pass it forward because commit_changes fetches it internally. This indirectly guides when to use the tool for reading vs. writing, but doesn't explicitly state when not to use it or compare with alternative read tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation and idempotency. The description adds value by explaining that arguments are independent and labels are replaced atomically, going beyond what annotations provide. However, it does not mention potential side effects like notifications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first lists updatable fields, second explains independence and replace semantics. Every sentence is essential, no wasted words, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, output schema present), the description covers the core behavior and usage pattern. It could mention prerequisites like issue existence or permissions, but the existing info is sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds meaning by stating independence of arguments and the replace semantics for list fields, which clarifies usage beyond the schema's 'New title' or 'Replace labels' descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing issue's specific fields (title, body, state, assignees, milestone, labels). It distinguishes from siblings like create_issue, get_issue, and list_issues by focusing on mutation of an existing issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'pass only the fields you want to change' and explains replace semantics for labels and assignees. It provides clear context for usage, though it does not explicitly state when not to use or name alternatives, but the sibling tools are distinct enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructive and non-read-only behavior. The description adds rich details: auto-detection of file existence, SHA-based updates, return of FileResponse, and conflict error raising. This goes beyond annotations to fully inform the agent of the tool's effects and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (~150 words) and well-structured with bullet points. It front-loads the purpose and includes only relevant details (auto-detection, return type, error handling, scope). No superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 required params, output schema exists), the description covers prerequisites (branch must exist), error handling (conflict retry), return type (FileResponse), and limitations (single-file only). The output schema provides return value details, so the description is complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 adds minimal parameter-specific detail beyond the schema (e.g., auto-detection is behavioral, not per-parameter). It marginally enriches understanding but does not significantly compensate beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or update a single file on a branch in one commit', providing a specific verb and resource. It distinguishes from siblings by explicitly noting that multi-file commits are out of scope and handled by Gitea's Git Trees API.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises when not to use the tool (multi-file scenarios) and mentions prerequisites (branch must exist; use create_branch first via the branch parameter description). It also provides error handling guidance (re-read and retry on conflict). However, it does not explicitly compare to other sibling tools beyond the multi-file exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral details about the three modes and the auto-fallback mechanism, which are not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear structure using bullet points for the three modes. Every sentence adds value, 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of an output schema, and comprehensive annotations, the description fully covers the tool's behavior, including edge cases like org fallback. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds significant context for the owner parameter beyond the schema, explaining the three modes and fallback. Page and limit are standard and already described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List repositories' and explains three modes based on the owner parameter. It distinguishes the tool from siblings like list_branches and list_issues by specifying the resource (repositories) and behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each mode (owner empty vs. user vs. org) and mentions the auto-fallback for organizations. However, it does not explicitly state when not to use this tool versus alternatives, though siblings make the distinction clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses two Gitea API calls made, fallback behavior for version unavailability, and return structure. Adds value beyond readOnlyHint and openWorldHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points for return fields. Front-loaded main purpose. Could be slightly more concise but very clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no input schema and annotations, description fully explains behavior and output. Covers fallback, return fields, and purpose comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; baseline 4 per guidelines. Description does not need to add param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns server and connection info, lists API calls and return fields, and distinguishes from siblings like get_server_version by being more comprehensive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
While not explicitly stating when to use vs alternatives, the description implies it's for diagnostics. The unique scope among siblings is clear, but no when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns the full Gitea PullRequest object with an additional 'comments_list' field, and explicitly states what is NOT included (inline review comments). This adds value beyond the annotations (readOnlyHint, openWorldHint) by explaining the exact return structure and scope. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a crucial clarification, all front-loaded. Every sentence provides essential information: purpose, relationship to another tool, and an explicit exclusion. No wasted words or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 3 parameters and existence of an output schema, the description is fully complete. It explains what the tool returns, what it does not return, and its conceptual alignment with get_issue. No gaps in context for effective agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters (owner, repo, pull_number). The description reinforces that pull_number is the issue number, but does not add significant semantic detail beyond the schema. Baseline 3 is appropriate as the schema already documents parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single pull request by number, including its discussion comments,' specifying the resource (pull request), action (get), and scope (including comments). It distinguishes from sibling tools like list_pull_requests (list vs single) and explicitly clarifies that inline review comments are not included, differentiating from potential review tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use this tool to retrieve a single PR with its comment thread. It excludes inline review comments and directs users to another endpoint for those, and notes the shape mirrors get_issue, aiding consistency. No ambiguity about when to use versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that the tool makes no network call and reports only the package version, confirming the openWorldHint=false annotation and adding context beyond the structured fields. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear sentences: first states purpose, second explains behavior. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and an output schema present, the description fully covers what the tool does and its behavior. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description does not need to add parameter info. A baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return the running gitea-mcp server's version', using a specific verb and resource. It distinguishes this tool from siblings that deal with external resources or network calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes 'No network call' and that openWorldHint is False, guiding when to use this tool. While it doesn't explicitly exclude alternatives, the unique nature of the tool makes this clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/werebear73/gitea-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server