gittr-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.5
Disambiguation2/5
Multiple tools overlap significantly, such as createPR vs createPRViaGittrCLI, getFile vs bridgeListFiles vs bridgeGetFileContent, and various bounty-related tools. The descriptions help but an agent would struggle to choose among convenience wrappers, low-level APIs, and redundant listing tools. This creates high ambiguity and misselection risk.
Naming Consistency3/5
Tool names follow camelCase but mix verb_first (listRepos, createIssue) and noun_first (bountyRelease, bridgeRepoExists) patterns inconsistently. Some names are verbose and oddly constructed (bountyCreateWithdraw, announceSoftwareFromForgeRelease). It's readable but lacks a predictable verb_noun convention.
Tool Count1/5
With 64 tools, this is an extreme number for an MCP server, far exceeding the 50+ threshold. Even though the platform has broad functionality, many tools are redundant or overly granular convenience wrappers. This makes the tool surface unwieldy and hard to navigate.
Completeness4/5
The server covers the full lifecycle of repositories, issues, PRs, bounties, stars/watches, and file operations, plus auth and paywall features. Notable gaps include no update/delete repo tool and no code search beyond repo names. Overall, the domain is thoroughly covered despite minor omissions.
Average 3.2/5 across 64 of 64 tools scored. Lowest: 1.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 37 commits in the last 12 weeks
- Last stable release on August 9, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
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.json to 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

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral aspects such as read-only semantics (GET is implied but not stated), authentication requirements, rate limits, or return format. The description carries the full burden and fails to address any behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single URL string, which is extremely short. However, this is under-specification rather than conciseness: it omits necessary explanatory content. A helpful description would be a few sentences explaining the tool's purpose and parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two required parameters, three optional, no output schema, and no annotations. The description provides no contextual information about behavior, response, or use cases. This is completely inadequate for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the five parameters (repo, limit, branch, bridgeUrl, ownerPubkey). The schema itself provides no parameter descriptions, so the tool is effectively unusable without external knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is only 'GET /api/nostr/repo/commits', which is an HTTP endpoint path rather than a clear statement of functionality. While the HTTP method and resource hint at listing commits, it lacks explicit action wording or a resource description that distinguishes it from siblings like getCommitHistory or bridgeListRefs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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 alternatives such as getCommitHistory or bridgeListRefs. The description provides no context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description carries no behavioral information beyond the HTTP method. It does not disclose side effects, return behavior, or any operational context. With no annotations available, the description completely fails to inform the agent about what happens when this tool is invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. It consists of a single endpoint string and does not earn its place by adding value. It is not a meaningful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and a 0% parameter coverage, the description is completely inadequate. The tool has moderate complexity with three parameters, but the description offers zero context, making it impossible for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the three parameters (repo, bridgeUrl, ownerPubkey). The agent is left without any semantic clues about what each parameter means or how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is just 'GET /api/nostr/repo/refs', which is an HTTP endpoint rather than an explanation of what the tool does. It restates the resource 'refs' without providing a verb or action, and does not clarify what listing refs means. This is close to a tautology, offering no insight into the tool's actual purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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 alternatives. Sibling tools like bridgeListFiles and bridgeGetFileContent exist, but the description does not differentiate this tool or suggest any context for using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only mentions that it is a POST request, implying a mutation, but says nothing about side effects, authorization requirements, reversibility, or what happens on success/failure. This is a significant gap for a tool handling funds.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and under-specified. While it is not verbose, it sacrifices necessary details for brevity, making it an under-specified snippet rather than a useful, front-loaded explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no output schema, no annotations), the description is completely inadequate. It does not explain the tool's purpose, parameters, behavior, or return value, leaving the agent with almost no contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 9 parameters with 0% description coverage, and the description provides no parameter information. It mentions 'recipient' generically but does not explain any of the fields like lnurl, bridgeUrl, issueRepo, or how they relate to the action. The description fails to compensate for the schema's lack of semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'claim withdraw to recipient' is vague and unclear. It does not convey the exact action: is it claiming a withdrawal or withdrawing a claim? The endpoint path adds some context, but the purpose remains ambiguous and does not distinguish it from sibling tools like bountyCreateWithdraw.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It simply states the endpoint and action, with no context about prerequisites, related tools, or appropriate scenarios. This leaves the agent without guidance on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose effects. It only states the endpoint and protocol; it does not explain side effects, auth requirements (despite lnbitsAdminKey/InvoiceKey in schema), or what happens when invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief, but it under-specifies rather than being efficiently concise. It provides a bare endpoint reference without meaningful elaboration, so it feels incomplete rather than crisp.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters, no output schema, no annotations, and no parameter descriptions. The one-line descriptor cannot adequately convey the operation, making it insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters are undocumented; the description does not clarify the meaning of amount, issueId, or the various URLs/keys. The schema provides only names and required status, leaving the agent to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the HTTP endpoint and the LNURL-withdraw mechanism, clearly indicating this tool creates a withdrawal for a bounty process. It has a specific verb (create-withdraw) and resource (bounty flow), but does not explicitly differentiate from sibling tools like bountyClaimWithdraw.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as bountyClaimWithdraw or createBountyInvoice. There are no conditions, prerequisites, or exclusions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It says nothing about side effects, required permissions, whether the operation is destructive, or what the response would be. The description only warns against a use case, providing zero transparency about the tool's actual behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (two sentences) and every word is used to redirect the user to alternative tools. It is well-structured for that narrow purpose, but it omits essential purpose information, so it is more under-specified than genuinely concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a tool with 7 parameters, no annotations, and no output schema. The description should explain the tool's purpose, when to use it, and behavioral caveats. Instead, it only provides exclusions and alternative tool names, making it grossly incomplete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 86% of parameters with descriptions, so the baseline is 3. The tool description adds no parameter semantics beyond the schema; it does not mention any of the seven parameters, leaving the schema to carry the weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description never states what createRelease actually does. It only provides a negation ('Not supported for UI release notes') and redirects to alternatives. The name implies creating a release, but the description lacks a clear verb+resource statement, making the tool's purpose ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit alternatives for two specific use cases: announceSoftwareFromForgeRelease for Zapstore/NIP-82 APK announce, and listReleases + publishRepoState for git tags. However, it never states the intended use case for createRelease itself, so the positive when-to-use guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It only states the endpoint and function, omitting any mention of read-only semantics, response format, permissions, or side effects. Since GET implies a read, but this isn't explicitly stated, the agent is left without critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and easy to read, with no wasted words. However, it's so brief that it lacks necessary detail, making it more under-specified than appropriately concise. It earns a middle score for being clear but not overflowing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 5 parameters, no annotations, and no output schema, this description is far from complete. It doesn't explain parameter roles, return values, or usage scenarios, so an agent cannot reliably invoke the tool correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description doesn't mention any parameters. All 5 parameters (path, repo, branch, bridgeUrl, ownerPubkey) are undocumented, leaving the agent without guidance on required combinations, defaults, or formats. The description completely fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (GET), the resource (file-content), and the context (from bridge), making it distinguishable from other file-related tools like getFile. However, it doesn't explicitly contrast with sibling tools or explain what 'bridge' means, so it's not a full 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like getFile or bridgeListFiles. The description is purely declarative and offers no contextual cues or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose safety and side effects. It indicates a write operation ('publish status') but doesn't mention whether it overwrites existing status, permission requirements, relay propagation, or preconditions like the issue being open. The '1632' status is unexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is under-specified. 'Convenience' adds a little context, but the sentence doesn't effectively front-load actionable information. It is short without being informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a mutation tool with 6 parameters and no annotations or output schema, the description fails to cover required context like side effects, security requirements (privkey), or relationship to sibling tools. It provides only a minimal hint, making it inadequate for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description offers no parameter explanations. Required params (issueId, ownerPubkey, repoId, privkey) and optional ones (relays, content) are left entirely to the schema, which the agent must already know. The description adds no meaning beyond implying 'issue'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: publishing status 1632 (closed) for an issue, which effectively means closing an issue. It is clear and distinguishes from siblings like reopenIssue by the 'closed' status, though the numeric code '1632' is somewhat cryptic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The word 'Convenience' hints it is a wrapper, but it doesn't explain when to prefer closeIssue over lower-level publishStatusForRoot or how it contrasts with reopenIssue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It only states the action without disclosing read-only nature, authentication requirements, pagination, or any side effects. The word 'explore' implies a read operation but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no fluff, but it's under-specified. It omits essential guidance about parameters, usage, and behavior, making it more incomplete than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no annotations, and a rich set of sibling tools (searchRepos, listRepos, getTrendingRepos), the description is far from complete. It lacks information about return format, filtering semantics, and alternatives, leaving the agent to guess when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes limit and category with descriptions, covering 67% of the parameters. The description's phrase 'by category/topic' aligns with the category parameter but adds no insight into limit or relays. The relays parameter remains undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Explore repositories by category/topic,' giving a clear resource (repositories) and a filter dimension (category/topic). However, the verb 'explore' is vague and could overlap with sibling tools like searchRepos or listRepos, and it doesn't specify the operation's output or scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage context is provided. The description doesn't indicate when to use exploreRepos versus searchRepos, listRepos, or getTrendingRepos, nor any prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden for behavioral disclosure. It only states the tool's purpose, with no mention of read-only status, authentication requirements, pagination behavior, return format, or potential side effects. This is insufficient for a tool that presumably fetches data from relays.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence. While this makes it easy to scan, it lacks details that would make the sentence earn its place beyond a basic purpose statement. It is compact but under-specified rather than efficiently complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are no annotations, no output schema, and three parameters including an undocumented one, the description is not complete enough. It fails to explain what the results look like, how relays affect the query, or any constraints like maximum limit. A simple enumeration tool would benefit from a mention of return format or filtering behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions cover 'limit' and 'minAmount' but not 'relays'. The description adds no parameter information at all, leaving 'relays' entirely unexplained. With 67% schema coverage and zero compensation from the description, there's a clear gap for the 'relays' parameter and no reinforcement of the covered ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Discover open bounties' with a parenthetical explanation of what constitutes a bounty (issues with bounty labels or Lightning funding). This is a specific verb+resource with scope, and it distinguishes from the sibling tool listBountiesForIssue, which is issue-specific. However, it doesn't explicitly mention that it returns a list or how results are ordered.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like listBountiesForIssue or submitBounty. There is no mention of prerequisites, intended use cases, or exclusions. The description only states what it does, not when to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It reveals that the tool publishes a status (mechanism), but does not describe side effects, permissions, whether the issue state is updated, or what happens if the issue is already open. The status code 1630 is mentioned without explanation, making the behavior only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no fluff. It is front-loaded with the core action. However, it is so brief that it omits critical information, but the conciseness itself is not the issue; the lack of substance is penalized in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four required parameters and no output schema or annotations, so the description must compensate. It does not explain the meaning of status 1630, the role of the required keys, or the expected outcome, leaving an agent with insufficient context to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the six parameters (issueId, ownerPubkey, repoId, privkey, relays, content). The description adds no meaning beyond the schema, leaving the agent to guess parameter relationships and required values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: publishing status 1630 (open) for an issue, which effectively reopens it. This is a specific verb+resource statement that distinguishes it from closeIssue and other siblings. However, it relies on the tool name to convey the full meaning and uses the vague qualifier 'Convenience' rather than explicitly stating 'reopens an issue.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like closeIssue or createIssue. The word 'Convenience' implies it is a shortcut, but there is no explicit context for when it is appropriate, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states that it pays a bounty, but does not mention that this is an irreversible financial transaction, requires admin keys (lnbitsAdminKey), or any side effects. The schema includes sensitive parameters but the description does not address them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with the HTTP method and endpoint, making it front-loaded and efficient. However, it is slightly cryptic with the dash separation, though it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no annotations, and no output schema, this description is severely incomplete. It fails to explain the required parameters (bountyId, recipientPubkey, bountyAmount), the role of bridgeUrl/lnbitsUrl, or the implications of releasing a bounty.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any of the 8 parameters. The phrase 'recipient Lightning address' vaguely references recipientLnurl or recipientLud16, but no parameter names, types, or usage details are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'pay bounty to recipient Lightning address' with an explicit endpoint 'POST /api/bounty/release'. It distinguishes itself from siblings like submitBounty and bountyClaimWithdraw by indicating this is the release/payment step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like submitBounty or bountyClaimWithdraw. It simply states the function without context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the signing requirement, which is useful, but fails to mention mutating side effects, authorization beyond signing, or the impact of creating the PR. This is a significant gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise and front-loaded, with no filler. However, it is arguably too terse for a complex tool, though the conciseness itself is well-executed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (10 parameters, no annotations, no output schema), the description is grossly incomplete. It does not explain the PR creation workflow, the meaning of signing, or how this tool relates to the CLI variant, leaving the agent under-informed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 10 parameters, and the description adds no parameter semantics. Beyond the parameter names (e.g., ownerPubkey, repoId, commitId), the description does not explain their roles or relationships, leaving the agent without essential input details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action and resource: "Create a pull request." This clearly differentiates it from siblings like createIssue (issues) and updatePullRequest (updates), which are distinct operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as createPRViaGittrCLI or updatePullRequest. The only extra hint, "REQUIRES signing," is a prerequisite rather than a usage guideline, and there are no exclusions or alternative tool mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Get branches' without explaining return format, authentication needs, side effects, or whether it lists all branches or a filtered set. The verb 'Get' implies a read operation, but no explicit safety guarantees are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant wording, making it appropriately concise. However, it is minimal to the point of under-specification, yet it still front-loads the core purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description should provide more context about what a branch object looks like, how repositories are identified, and how the 'relays' parameter affects behavior. The current description is insufficient for an agent to fully understand the tool's inputs and outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, with 'relays' lacking any description. The description adds no explanation of parameter purpose or format, leaving the optional 'relays' parameter ambiguous and not compensating for the incomplete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the resource 'branches for a repository', making the purpose unambiguous. It is distinct from sibling tools like getRepo or listRepos, but lacks explicit differentiation from similar ref-listing tools such as bridgeListRefs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description simply states what it does without any context about selection criteria, prerequisites, or when other tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states what information is returned (push cost and paid intent status) but does not disclose whether the operation is truly read-only, requires authentication, or what happens if the paywall is not set up. The 'GET' prefix implies read-only but is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It does not waste words, though it is so terse that it omits important context. It earns its place but leaves the reader wanting more.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and a 7-parameter input schema, this description is severely underspecified. It fails to explain return format, parameter semantics, or usage context relative to siblings, making it inadequate for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 7 parameters with 0% coverage in the description, and the description itself mentions none of them. Even though some parameter names are self-explanatory (ownerPubkey, repo), several like ownerBlinkApiKey and ownerLnbitsReadKey need clarification, and the description provides no compensation for the schema's lack of property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves push cost and whether the payer has paid intent, using a GET verb against a specific resource. It is distinct from sibling tools like createPushPaywallIntent or syncRepoPushPolicy, though it does not explicitly mention those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied by the description: checking push payment status and cost. However, it gives no explicit guidance on when to choose this over related tools (e.g., createPushPaywallIntent) or what prerequisites (like having a paywall intent) exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only implies a copy operation without detailing side effects, permissions, or whether existing repositories may be overwritten. There is no mention of needed credentials or rate limits, leaving significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It immediately communicates the verb and the object, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no output schema, and no annotations, a one-sentence description is severely insufficient. It lacks information on prerequisites, return values, side effects, or how this relates to other repository tools. The description cannot adequately prepare an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no information about any of the 7 parameters, and with schema coverage at 71%, there are still unclear parameters like relays and graspServer. While the schema covers most parameters, the description fails to clarify the overall data flow or the role of these parameters in the mirroring process.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Mirror') and the specific resources involved ('GitHub/GitLab repo' and 'gittr.space'), making the core purpose unambiguous. However, it does not explicitly differentiate this from sibling tools like importRemoteToBridge or createRepo, which may overlap in functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites such as authentication or existing credentials. It does not explicitly exclude any use cases, but it also gives no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'check if repo exists' without disclosing the return format (e.g., boolean, HTTP status), error behavior, or whether it performs a network call to the bridge. No side effects or failure modes are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the purpose. It is not overly verbose, but it lacks necessary details; however, for conciseness alone it earns a decent score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and no parameter explanations, the description is incomplete for safe invocation. An agent cannot predict the outcome or interpret a response. The tool complexity is low, but the description still fails to provide essential context beyond the purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters with 0% description coverage. The description does not explain what 'ownerPubkey', 'repo', or 'bridgeUrl' mean, nor how they are used in the existence check. The agent must guess their semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact HTTP endpoint ('GET /api/nostr/repo/exists') and the operation ('check if repo exists on bridge'), making it clear this is a boolean existence check distinct from sibling tools like getRepo or listRepos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, no prerequisites, and no mention of whether it should be called before other operations. The agent is left to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 owner wallet keys are passed in the body, but does not state side effects, authentication requirements, rate limits, or whether the intent is immediately redeemable. The mutating nature is only implied by 'create'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact line, which is efficient, but it is more of an API endpoint label than a structured explanation. It contains no sentences and lacks logical breakdown of purpose, usage, and parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, no output schema, and no annotations, this description is severely under-specified. It provides no information about the request/response flow, prerequisites, or return value, making it inadequate for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 1 of 8 parameters has schema documentation (13% coverage). The description adds a vague reference to 'owner wallet keys in body', which hints at the owner* parameters, but does not explain repo, bridgeUrl, payerPubkey, or the LNBits/Blink parameters. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the action as creating an invoice/payment intent for pay-to-push, which is a specific verb+resource. It distinguishes itself from sibling tools like pushToBridge and bounty invoice tools. However, the phrasing is cryptic, relying on HTTP jargon ('POST') and the action name 'create_intent' instead of a plain-language verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidance or alternative tools are mentioned. The phrase 'invoice for pay-to-push' implies the tool is used when a push requires payment, but there is no context on when not to use it or how it relates to sibling tools like getPushPaywallStatus or syncRepoPushPolicy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Get trending/popular repositories' and does not mention authentication, rate limits, the criteria for 'trending', or any side effects. For a tool with no annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is concise but under-specified. It earns its place as a clear label, but it could easily include a sentence about usage or parameters without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations, no output schema, and only a minimal one-line description. The meaning of the relays parameter and the expected response shape are left undocumented, making the context incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for limit and timeRange, but relays lacks a description, and the tool description does not compensate. With 67% schema coverage (not high), the description should have clarified the missing parameter, but it adds no parameter information at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get trending/popular repositories' uses a specific verb ('Get') and resource ('repositories'), and the 'trending' qualifier helps distinguish it from sibling repo-listing tools like listRepos or exploreRepos. However, 'popular' is somewhat vague, and no further details are given about what constitutes trending or popular.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for when you want trending/popular repositories, but it provides no explicit guidance on when to use it versus the many sibling tools (e.g., listRepos, searchRepos, exploreRepos). No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects, but it only says 'publish status' without explaining the implications (e.g., it publishes to relays, requires a private key, or changes PR state). The description provides minimal insight into the tool's behavior or consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It front-loads the core purpose. While it could be more detailed, the conciseness itself is a strength, though it borders on under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, no annotations, and no output schema, the one-sentence description is severely inadequate. It doesn't explain the status code, the 'PR root event' concept, parameter purposes, required inputs, or return values, leaving the agent with insufficient information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it fails to explain any of the 7 parameters (prId, ownerPubkey, repoId, privkey, relays, content, mergeCommitId). The only hint is 'status 1631', which doesn't map to any parameter. This leaves parameter meaning almost entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: publish status 1631 (merged/applied) for a PR root event. It uses a specific verb and resource, and the phrase 'Convenience' hints at a specific utility. However, 'PR root event' is somewhat jargon-heavy and not fully clarified, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'Convenience' and the specific status code, suggesting it's a shortcut for marking a PR as merged. However, there is no explicit comparison to alternatives like publishStatusForRoot or mergePullRequest, and no clear exclusions or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It implicitly indicates a read-only GET request, but does not mention edge cases, auth requirements, rate limits, or response format, leaving significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clean sentence with no wasted words. However, it is quite terse and under-specified, which slightly reduces its effectiveness despite being concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, no output schema, and no annotations, the description is far from complete. It only states the core action without explaining required context, the role of bridgeUrl, or how results are returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only hints at the 'branch' parameter. Other parameters such as ownerPubkey, repo, bridgeUrl, and includeSizes are left unexplained, adding minimal value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'GET /api/nostr/repo/files — list files for branch'. It specifies the HTTP method and endpoint, distinguishing it from sibling tools like getFile, bridgeListRefs, and bridgeListCommits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It mentions 'soft-delete' (non-destructive) and 'owner only' (permission), but does not explain what soft-delete means in practice (e.g., recoverability), any side effects, or what happens to the repository. This is a significant gap for a mutating tool with zero annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the alias relationship and the action. There is no wasted wording, and the structure is direct. However, it is extremely brief, which compromises completeness, but for pure conciseness it earns a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain return values, parameter usage, or the practical implications of 'soft-delete'. The reliance on an alias to softDeleteRepo does not stand alone, as no details from that tool are provided here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no parameter details. There are 5 parameters (name, relays, repoId, privkey, description) but the description does not explain their roles or how to use them. The 'owner only' hint is too vague to compensate for the complete lack of parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('soft-delete'), the resource (a NIP-34 repository), and the access restriction ('owner only'). It also distinguishes itself from the sibling softDeleteRepo by explicitly noting it is an alias, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Alias for softDeleteRepo' implies the tool is used interchangeably with softDeleteRepo, which is a form of usage guidance. The 'owner only' note adds a prerequisite. However, it does not explicitly state when to choose this over other deletion alternatives or when not to use it, leaving the guidance somewhat implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'Fork an existing repository' does not mention side effects (e.g., creating a new repository), authentication requirements, or effects on the source repository. This is a significant gap for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler, fully front-loaded with the essential action. It earns every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no annotations, and no output schema, the one-sentence description is insufficient. It does not explain the forking workflow, return values, or consequences, leaving the agent without crucial context for a complex operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (6 of 8 parameters have descriptions), so the schema already documents most parameter semantics. The description adds no parameter-specific information, but the coverage is high enough that the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fork an existing repository' uses a specific verb (fork) and resource (repository), clearly stating the action. It distinguishes from siblings like createRepo and mirrorRepo, though it doesn't elaborate on the nuances of forking versus those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use forkRepo over alternatives such as mirrorRepo or createRepo. The description simply states the action without context or exclusions, leaving the agent to infer usage purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It merely states 'Get commit history' without disclosing behavior such as default branch handling, pagination limits, whether it is a read-only operation, or the role of the 'relays' parameter. The description adds minimal value beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler words. It is front-loaded with the verb and resource. However, it is slightly under-specifying for a 5-parameter tool, but the conciseness itself is strong.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and 5 parameters, the description is too minimal to be complete. It does not explain what the returned commit history looks like, how branches are handled, or what 'relays' means in this context. The description leaves too much for the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 4 out of 5 parameters (80% coverage), so the baseline is 3. The description itself adds no parameter semantics; it relies on the schema's descriptions for the parameters. The 'relays' parameter lacks a schema description, but the description does not compensate for that gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Get commit history') that clearly states the tool's function. It does not explicitly distinguish from siblings like bridgeListCommits, but the term 'repository' provides a distinct context, so it earns a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It does not mention that it operates on repository commit history as opposed to bridge commits, nor does it provide any contextual hints about suitable scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, whether credentials are needed, or what algorithm is used. It also doesn't mention side effects or return behavior beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, a single sentence that directly states the action. For a tool with one parameter, this length is acceptable, though it could be slightly more informative without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does not specify the return format (e.g., compressed/uncompressed, hex, base64) or any edge cases. Given the simplicity of the tool, some return details are still necessary for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for the single parameter (privkey is a 64-char hex private key). The description adds no additional meaning; the phrase 'from private key' merely restates what the parameter already conveys. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: deriving a public key from a private key. It is specific enough to distinguish from any sibling tools, though it doesn't explicitly name alternatives or elaborate on the context of use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives, no prerequisites, and no security warnings. The description is a bare one-liner that provides no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states 'Publish' without disclosing behavioral traits such as requiring a private key for signing, broadcasting to relays, or being a write operation. Since no annotations are provided, the agent lacks safety/behavioral context, which is critical for a tool with sensitive parameters like privkey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (one short sentence), but under-specification is not conciseness given the tool's complexity. With 13 parameters and no annotations, the description needs to convey much more context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has a large parameter set, no output schema, and no annotations. The one-sentence description fails to explain the event structure, authentication requirements, return behavior, or any other contextual detail needed for correct usage. It is completely inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about any parameters. The input schema has 13 parameters but only one has a description (8% coverage), so the description fails to compensate for the schema's poor documentation. Key parameters like privkey, issueId, and amount are left unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action 'Publish' and the specific resource 'gittr bounty metadata event (kind 9806)', making it clear what the tool does. It distinguishes itself from sibling tools like publishRepoAnnouncement and publishRepoState by specifying the event kind.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for publishing bounty metadata events via the event kind, which provides clear context. However, it doesn't explicitly mention alternatives or exclusions, but given the specificity, it's not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It mentions the signing requirement, which is useful, but it does not disclose side effects, mutation nature, or what the published announcement entails beyond the kind. This is insufficient for a publishing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the verb and resource, and the 'REQUIRES signing' addendum is essential. It is concise with no filler, ideal for a tool with minimal metadata.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 9 parameters, 4 required ones, no output schema, and no annotations, this one-sentence description is severely incomplete. It lacks information about expected behavior, return values, side effects, or interaction with other tools like syncRepoPushPolicy, leaving the agent without enough context to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description adds no parameter meaning. It does not explain what parameters like repoId, name, relays, or web are for, nor how they relate to the publication. The description fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Publish repository to Nostr') and specifies the event kind (30617), making the tool's purpose unambiguous. It distinguishes itself from sibling tools like publishRepoState or publishSoftwareAnnounce by explicitly referencing the repository announcement kind.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as publishRepoState or publishSoftwareAnnounce. The only contextual note is 'REQUIRES signing', which is a prerequisite rather than a usage scenario or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden. It discloses that the tool republishes a kind 10018 event, which implies a Nostr publish side effect. However, it does not mention auth requirements (e.g., privkey), reversibility, or the impact on an existing watch list, leaving key behavioral traits undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, using a parenthetical to clarify the mechanism. It is well-structured and front-loaded with the verb, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and a bare description, the tool lacks information about return values, error conditions, or prerequisites. The side effects beyond the republish action are unclear, and the parameter semantics are entirely missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% coverage), and the description does not explain the roles of ownerPubkey, repoId, privkey, or relays. The agent is left to guess what each parameter does, which is especially problematic for privkey and relays.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Unwatch a repo') and the mechanism ('republish kind 10018 without this repo'), making it distinct from sibling tools like watchRepo and unstarRepo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the tool name and the 'unwatch' action, but there is no explicit guidance on when to use this tool versus alternatives like unstarRepo or starRepo. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It does not mention pagination, return format, authentication, rate limits, or the purpose of the 'relays' parameter. The description is purely syntactic and adds no transparency beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is appropriately sized for the simplicity of the operation, though it lacks any additional structured guidance that could aid the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should explain return values, filtering behavior, and the role of 'relays'. It does none of this, making the description incomplete for an agent to fully understand invocation outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the baseline is 3 even though the description itself mentions no parameters. The schema already explains labels, repoId, and ownerPubkey, but the description does not compensate for the undocumented 'relays' parameter, leaving a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists issues for a repository, using a specific verb and resource. It distinguishes from sibling tools like getIssueById (single issue) and createIssue (creation), and is unambiguous about its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as listPRs or getIssueById. The description merely states the action without context, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.
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?
With no annotations, the description carries the burden of behavioral disclosure. It states 'REQUIRES signing', which is a clear auth prerequisite, and 'publish to Nostr' implies an external side effect. However, it does not disclose reversibility, response behavior, or other side effects, leaving some gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action and includes only essential information (target, kind, signing requirement). No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations, combined with 0% parameter coverage, means the description must explain all behavior and inputs. It leaves multiple required parameters undefined and does not mention return values or errors. Incomplete for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate. It only hints at privkey via 'signing' but leaves repoId, refs, and relays entirely unexplained. This is a critical gap for a tool with 4 required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Publish' and clearly identifies the resource 'repository state to Nostr (kind 30618)'. This differentiates it from sibling publish tools like publishRepoAnnouncement and publishBountyToNostr by specifying the exact event kind and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The description does not mention exclusions, prerequisites (beyond signing), or contrast with sibling publish tools. Usage context is only implied by the name and action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It fails to disclose that publishing requires a private key (privkey param), signs an event, or broadcasts to relays. The word 'Publish' implies a network operation, but consequences and requirements are not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no redundancy; every phrase carries meaning. It includes the NIP spec, kind, and the core update content, making it highly economical and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no annotations, no output schema), the description is far from complete. It does not explain the event structure, required dependencies, side effects, or expected outcomes, leaving an agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description is responsible for explaining the 10 parameters. It only references 'new tip commit' and 'clone URLs', which likely correspond to currentCommitId and cloneUrls, but leaves the other 8 parameters (e.g., ownerPubkey, repoId, pullRequestEventId, privkey) unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Publish' and identifies the resource as 'NIP-34 PR update (kind 1619)', making it distinct from sibling tools like createPR or mergePullRequest. The parenthetical 'new tip commit + clone URLs' further clarifies the update payload, showing exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives like createPR or mergePullRequest. The context is implied by the name and description, but no prerequisites, exclusions, or alternative scenarios are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only describes the action without revealing what happens if the issue is not found, whether it tries all relays or stops at the first, or any error behavior. This lack of detail is a significant gap for a network-fetching tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler, front-loaded with the action verb. However, the inclusion of '1621' without explanation could confuse users, slightly reducing clarity while still being concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a fetch tool with no output schema and no annotations, the description is under-specified. It fails to mention the return value, relay behavior when none are provided, error cases, or the meaning of '1621'. A more complete description would cover these aspects to help the agent understand the tool's behavior and output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It clarifies that issueId is used to fetch the issue, but it does not explain the relays parameter at all—whether it is optional, what default behavior is, or how relay selection works. The description adds minimal value beyond the schema's basic names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch', the resource 'single issue event (1621)', and the identifier 'by id', making the tool's purpose unambiguous. It distinguishes itself from siblings like listIssues (which lists multiple issues) and getPullRequestById (different entity type).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single issue by its ID, but it does not explicitly state when to use this tool instead of alternatives such as listIssues or getPullRequestById. No exclusion or alternative guidance is provided, so the usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It merely says 'Get contributors', which essentially restates the tool's name. It does not disclose whether the result is paginated, what fields are returned per contributor, or whether any ownership/auth checks apply beyond the parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single six-word sentence that starts with the action and clearly states the object. There is zero filler or repetition, which is ideal for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters, no output schema, and no annotations, a description of this brevity is insufficient. It does not define what 'contributors' means in terms of returned data, how the relays parameter affects behavior, or any error conditions an agent should anticipate. An agent would need to make significant assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (two of three parameters have descriptions), so the baseline is 3. The description adds no additional meaning beyond the schema for repoId and ownerPubkey, and it does not explain the optional relays parameter at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a clear resource ('contributors to a repository'), which immediately conveys the tool's function and distinguishes it from sibling tools like getRepo or listRepos. The tool name reinforces this, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives, nor any mention of prerequisites such as the repository existing or the owner having a specific role. With many repo-related sibling tools, an agent gets no explicit direction on selecting this tool or handling edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It mentions 'refetch' but does not explain side effects (e.g., overwriting existing repos), authentication requirements, or network behavior. The mutation implications are unclear, making this insufficient for a server-side clone operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the core action efficiently. However, the term 'refetch' is vague and the sentence is slightly dense, but no words are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and four parameters, this minimal description is insufficient. It does not cover return values, error conditions, prerequisites like credentials, or how this interacts with existing bridge repositories, leaving significant gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only indirectly adds meaning to cloneUrl ('GitHub/Git URL') and repo ('owner/repo'). It fails to clarify bridgeUrl or ownerPubkey, leaving two of four parameters undefined beyond raw names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Server-side git clone into bridge') and the specific resource ('import GitHub/Git URL into owner/repo on gittr'). It distinguishes from sibling tools by focusing on importing external URLs, unlike pushToBridge or mirrorRepo which cover other workflows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for importing remote git URLs into a bridge repo, but does not explicitly state when to use this tool over alternatives like pushToBridge or mirrorRepo. No exclusions or alternative names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only says 'List', implying a read operation, but fails to mention return format, authentication needs, pagination, or any other behavioral characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary wording, making it appropriately concise and well-structured for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a minimal viable description for a straightforward list operation, but it lacks usage guidance and behavioral details. With no output schema or annotations, the description could be more complete, though it is not severely deficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes ownerPubkey and repoId but leaves relays undocumented. The description adds no parameter semantics, and with 67% schema coverage it does not compensate for the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('pull requests') with a scope ('for a repository'), clearly distinguishing it from sibling tools like listIssues, getPullRequestById, and createPR.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as listIssues or getPullRequestById. It does not mention context, exclusions, or alternative tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and only discloses the status kind meanings. It does not mention that this creates and broadcasts a Nostr event, the need for a private key, relay behavior, or other side effects, which is significant for a publish/mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with a compact parenthetical, front-loads the primary verb and resource, and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter mutation tool with no output schema, annotations, or meaningful schema descriptions, this description is entirely inadequate. It does not explain required parameters, prerequisites, return values, or how it fits with the broader set of repo/issue tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 8%, so the description must compensate, but it only adds semantics for statusKind (1630/1631/1632/1633). Critical parameters like rootEventId, ownerPubkey, rootEventAuthor, and privkey remain unexplained in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description provides a specific verb ('Publish') and resource ('NIP-34 status for an issue, PR, or patch root event'), including the exact status kind mapping. This clearly distinguishes it from sibling tools like publishRepoAnnouncement or closeIssue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for publishing NIP-34 statuses on issue/PR/patch root events, but it does not state when to prefer this over alternatives or any exclusions. There is clear context but no explicit guidance or comparison to related publishing/merging tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It only states the action without mentioning side effects, auth requirements, prerequisites, or return values. For a mutation tool, this is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficiently worded sentence that front-loads the core action and uses a parenthetical to add clarifying context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 5 parameters, 3 required, and no output schema or annotations, the description is minimal. It doesn't explain expected outcomes, the role of optional parameters, prerequisites, or what happens after submission. The tool would be hard to use correctly with only this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already documents most parameters. The description adds minimal value by tying PR/evidence to the submission action, but it doesn't explain optional params like relays or privkey beyond what the schema says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (submit work) and the resource (bounty), with a parenthetical clarifying the claim mechanism (PR/evidence). It distinguishes from sibling bounty tools like bountyClaimWithdraw by focusing on submission, but could be more explicit about what 'work' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is used when you have a PR and evidence to claim a bounty, but it does not provide explicit guidance on when to use this instead of related tools like bountyClaimWithdraw or how to prepare prerequisites. No alternatives or exclusions are mentioned.
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?
With no annotations, the description carries the full burden of behavioral disclosure. 'Discover' reasonably implies a read-only operation, and the mention of NIP-34 adds useful protocol context. However, it does not explicitly state that the operation is safe, nor does it mention anything about rate limits, side effects, or return behaviors, so it is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main action, and contains no redundant information. It is appropriately concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list/discovery tool with four parameters and no output schema, the description is adequate but leaves gaps. It does not mention the default limit, the optional nature of relays, or how this relates to other discovery tools, but the schema covers the parameter details. The description could be richer in explaining what the agent should expect when invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters with descriptions, so the baseline is 3. The description adds a slight nuance by summarizing that filtering is by 'pubkey or search term,' which helps convey the purpose of two parameters, but it does not compensate fully for the lack of any additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Discover' and clearly identifies the resource ('repositories from Nostr relays (NIP-34)') and the filtering capability. It is clear in its intent but does not explicitly distinguish itself from sibling tools like searchRepos or exploreRepos, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as searchRepos, exploreRepos, or myRepos. It simply states what it does without any context on preferred use cases or exclusions, offering no help in tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states 'POST' and 'upsert', indicating a mutation, but does not disclose auth requirements, reversibility, response format, or side effects. It also fails to explain the role of bridgeUrl in the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the API endpoint and purpose. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description is too brief to provide complete context. It does not explain what the upsert does to the bridge, what the response is, or what bridgeUrl is for, leaving critical gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%; only signedAnnouncementEvent has a description. The description adds clarity by telling users to use the event JSON from publishRepoAnnouncement, but leaves bridgeUrl completely undocumented, offering no compensation for the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'upsert push paywall from signed kind 30617', with a specific verb and resource. It distinguishes from sibling tools like getPushPaywallStatus by indicating a write operation and references the source event from publishRepoAnnouncement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical 'use announcement event JSON from publishRepoAnnouncement' implies the tool is used after publishing an announcement, but it does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusion criteria are given.
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?
With no annotations provided, the description carries the burden of disclosure. It does reveal a key non-obvious behavior: the operation 'republishes full announcement' rather than simply updating a tag. However, it does not describe other important implications, such as whether the maintainer list is additive or replaced, potential side effects, or required authentication beyond what the schema mentions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with a parenthetical that packs important mechanism details. It is front-loaded with the primary action and avoids unnecessary words, though the parenthetical makes it slightly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations, no output schema, and limited description. It explains the republishing mechanism but not the full effect on the announcement, whether it is destructive, what the expected outcome is, or any prerequisites. The reference to 'matches gittr UI' may be unhelpful to users unfamiliar with that UI, leaving the description incomplete for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 60% (three of five parameters have descriptions), and the tool description does not clarify the remaining parameters (relays, repoId) or add meaning to the existing ones. While 'maintainer' hints at collaboratorPubkey, the description fails to compensate for the uncovered parameters, so it adds little semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add maintainer') and the specific resource ('kind 30617'), and it distinguishes the tool from sibling tools by detailing the underlying mechanism ('republishes full announcement with updated maintainers tag'). The reference to 'matches gittr UI' adds further specificity, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one wants to add a maintainer, but it does not explicitly state when to use this tool over alternatives or provide exclusions. The mention of matching the gittr UI provides some context but no direct guidance on alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It reveals that the tool performs an exact forge URL to npub mapping and is GitHub-specific, which is useful behavioral context. However, it does not discuss any other behaviors (e.g., return format, auth, rate limits, error handling) that might differ or be inherited from findReposBySource.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core alias relationship, and contains no filler. Every word earns its place, and the secondary sentence provides essential usage guidance without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters with many overlapping names (github/githubs, source/sources), no annotations, and no output schema, the description is too brief to stand alone. It relies on the agent already knowing findReposBySource. It does not explain parameter relationships, defaults, or the return value, leaving significant gaps for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only 'github' is described). The description adds minimal parameter meaning—the phrase 'exact forge URL' relates to the 'github' parameter but does not explain any of the other five parameters (limit, relays, source, githubs, sources). This is insufficient compensation for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is an alias for findReposBySource and hints at the core function 'exact forge URL → npub'. It distinguishes itself as the GitHub-specific variant by referencing the alternative for non-GitHub forges. However, the arrow notation is cryptic and the actual operation is not fully spelled out.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence gives explicit guidance: 'Prefer findReposBySource for non-GitHub forges.' This tells the agent when to use this tool vs the primary alternative. It does not mention other sibling tools like searchRepos or listRepos, but for an alias, the guidance is clear and sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the search scope and does not mention return format, default behavior, authentication, or rate limits. This is a significant gap for a tool with no 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant words. It is front-loaded and immediately conveys the tool's primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description must explain more about the tool's behavior, such as what it returns and any limitations. It does not provide this, making it incomplete for an agent to understand the full invocation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%. The description adds meaning to the 'query' parameter by specifying it searches repository names and descriptions, but it does not clarify the 'relays' parameter, which is left entirely undocumented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('search') and clearly identifies the resource scope ('repository names and descriptions'). It distinguishes itself from siblings like listRepos and getRepo, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for finding repositories by text query, but it does not explicitly state when to use it over alternatives or mention any exclusions. There is no guidance on context such as 'use this when you need to search by keywords'.
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?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose that signing is required and implies a write operation, but it does not explain the signing mechanism, side effects, or permission requirements beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and flags a critical requirement. There is no filler or redundant wording; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With seven parameters, no annotations, no output schema, and no parameter descriptions, one sentence is insufficient. The description omits return value expectations, signing details, and how this tool relates to other issue/PR operations in the same domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no parameter-level detail. 'REQUIRES signing' hints at the privkey parameter, but otherwise required fields like ownerPubkey, repoId, and relays are left entirely to their self-evident names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and direct object ('Create an issue'), which clearly identifies the action and resource. It is distinct from related sibling tools like listIssues, closeIssue, and reopenIssue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite ('REQUIRES signing') but provides no explicit guidance on when to use this tool versus alternatives such as createPR or listIssues. Usage context is mostly implied by the tool name and sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'from relays,' implying network fetch and no mutation, but omits details like behavior on missing id, error handling, or read-only confirmation. The description is too terse for adequate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action and resource. Every word serves a purpose, and the structure is immediately scannable. Exceptionally concise without losing necessary meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but no output schema or annotations exist. The description covers the core action but lacks return value explanation, error behavior, and relay usage semantics. It's adequate for a straightforward fetch, but leaves gaps for a less inferential agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description partially compensates by linking 'by id' to prId and 'from relays' to relays. However, it does not specify parameter formats, constraints, or optionality nuances beyond the schema's bare names. The mental model is basic but functional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Fetch' and the resource 'single PR event (1618)' by id, distinguishing it from sibling tools like listPRs (list) and createPR (create). The mention of '(1618)' contextualizes the Nostr event kind, adding domain-specific clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: fetch a single PR by id. It does not explicitly contrast with alternatives (e.g., listPRs) or state when not to use. The description offers minimal guidance on when to choose this over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral weight. It only says 'List' and mentions the event kind, but does not disclose return format, pagination, relay behavior, or any side effects. It is a read operation but lacks sufficient detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no filler. Efficiently communicates the core action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no output schema, the description is too minimal. It does not explain what kind 9806 events are, how relays are used, or what the response looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero description coverage, and the description only explains the 'issue id' linkage (issueId parameter). The optional 'limit' and 'relays' parameters are not explained, leaving significant ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'List' with resource 'kind 9806 bounty events' and scope 'linked to an issue id'. This clearly distinguishes it from sibling listBounties which likely lists all bounties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context that this tool is for finding bounty events associated with a specific issue ID. However, it does not explicitly mention when to avoid it or mention alternatives such as listBounties.
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?
There are no annotations, so the description carries full disclosure burden. It does add meaningful context that the data comes from the 'latest kind 10018 followed-repos event' on relays rather than a live repository list, but it omits details like error behavior, default relay handling, and return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It efficiently communicates the action and the data source without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and only a minimal description, the tool lacks crucial context like expected output shape, whether pubkey is required, what happens if no followed-repos event exists, and how relays are used. This makes it incomplete for an agent to invoke confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and no per-parameter documentation. The description only vaguely hints at 'your' (suggesting pubkey) and 'on relays' (suggesting the relays array), but it does not explicitly explain the semantics or required format of either parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'List' plus a specific resource ('repos from your latest kind 10018 followed-repos event on relays'), clearly identifying what the tool does. It also distinguishes itself from siblings like listRepos and myRepos by referencing the Nostr event type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you want repos from a user's latest followed-repos event), but it does not explicitly state when to prefer this over alternatives such as listRepos or listStars. No exclusionary guidance is provided.
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?
With no annotations, the description must carry the behavioral burden. It discloses that the tool reads from .nostr-keys.json, which is useful context, but does not clarify read-only nature, error scenarios, or output format. For a simple list operation, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core purpose and adds a specific detail about the identity source. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional param, no output schema), but the description still leaves a major gap: the 'relays' parameter is unexplained, and no return value or output format is described. It provides enough for a basic understanding but is incomplete for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional parameter 'relays' with 0% schema description coverage, and the tool description does not mention or explain it at all. The description fails to compensate for this gap, leaving the parameter's purpose and behavior completely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists repositories owned by the current user, with a specific source file (.nostr-keys.json). It uses a specific verb (list) and resource (repositories), and the owner scope distinguishes it from sibling tools like listRepos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this is for the current user's own repositories, sourced from local Nostr credentials. It implies a use case but does not explicitly state when to use it instead of similar tools like listRepos, nor does it mention exclusions.
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?
No annotations are provided, so the description carries the burden of disclosing behavioral traits. It explicitly mentions 'full flow including git push', which is a key mutating behavior beyond just creating a PR. However, it does not disclose potential side effects, auth requirements, failure modes, or reversibility, leaving transparency incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that captures the essential purpose and key behavioral detail (full flow with git push). Every word adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no output schema, and no annotations, the description is too sparse. It fails to mention what the tool returns (e.g., PR URL), what the 'full flow' entails in detail, prerequisites like credentials, or how it handles errors. The recommendation is helpful but does not compensate for the missing operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters, each with descriptions, so the baseline is 3. The tool description adds no additional parameter semantics beyond the schema, as it only mentions the CLI and push flow but does not explain parameters like privkey, repo, or branches.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a pull request via the gittr CLI and includes the full flow with git push, distinguishing it from the sibling createPR tool. The use of 'RECOMMENDED' adds a preference but does not explicitly name the alternative, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit recommendation ('RECOMMENDED for PRs') and indicates the full flow includes git push, which implies this tool is the preferred choice for PR creation. However, it does not explicitly state when not to use it or name specific alternatives, so it lacks exclusivity 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?
With no annotations, the description carries full transparency burden. It discloses the underlying behavior in detail: publishes replaceable event 30617 with deleted markers and a NIP-09 kind 5 on the 'a' tag. However, it does not mention side effects, reversibility, or permission requirements beyond 'owner'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that front-loads the core purpose and includes precise technical detail. Every phrase adds value, from the NIP spec to the alias, without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and no annotations, the description provides substantial protocol-level context, including the exact Nostr event types and tag format. It lacks guidance on prerequisites (e.g., key loading) and parameter usage, but the core operation is well-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40% (repoId and privkey have descriptions). The description does not explain any parameters; it references 'owner' and 'repo' generically but doesn't connect them to schema fields. Thus it fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs an owner soft-delete for a NIP-34 repo, with specific protocol actions ('publish replaceable 30617 with deleted markers + NIP-09 kind 5'). It provides a concrete alias 'deleteRepo', but this alias overlaps with a sibling tool, so it doesn't clearly distinguish from that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is for owner-driven soft deletion ('Owner soft-delete') and gives a user-facing comparison ('same as gittr Settings → Delete'). However, it does not explicitly discuss when to use this over alternatives like the sibling 'deleteRepo', and the alias statement could cause confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions publishing a NIP-51 kind 10018 list, but does not disclose that this is a replaceable event that may overwrite the user's existing followed-repos list, nor does it clarify whether it is additive or destructive. The 'full `a` tag set' phrase is ambiguous and could mislead an agent about side effects. More transparency is needed for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that front-loads the action ('Watch a repo') and packs essential context into a parenthetical. Every phrase contributes meaning, with no filler or repetition. It is an appropriate length for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool writes a replaceable NIP-51 event, yet the description omits critical context such as overwriting behavior, required authentication (though privkey is auto-loaded), return value (no output schema), and how it interacts with unwatchRepo or listWatchedRepos. With no annotations and no output schema, the description is too thin to fully inform an agent about side effects or expected results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 75% of parameters with basic descriptions (ownerPubkey, repoId, privkey), leaving relays undefined. The description's mention of 'full `a` tag set' hints that ownerPubkey and repoId form an address tag, adding some meaning beyond the schema, but it does not explain how each parameter is used or clarify the optional relays parameter. The description contributes moderate value but does not fully compensate for the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Watch a repo'. It further specifies the protocol (NIP-51 kind 10018) and the action (publishes full `a` tag set), and draws a comparison to the 'gittr Watch button' for clarity. This distinctly separates it from siblings like starRepo, unwatchRepo, and listWatchedRepos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to watch/follow a repo) and provides operational context (publishes NIP-51 list). However, it does not explicitly state when not to use it or name alternatives such as unwatchRepo or starRepo, so it falls short of the highest bar but still conveys clear intended usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full transparency burden. It only states the retrieval action and identification methods, without disclosing error behavior (e.g., what happens if the repo is not found), authentication needs, relay usage (despite the 'relays' parameter), or return format. This leaves significant behavioral details uncovered for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant details. It communicates the core purpose efficiently and earns its place without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (a single repo getter), but with no output schema and no annotations, the description is thin. It does not mention return values, error handling, or the purpose of the 'relays' parameter, making it adequate but with clear gaps. A bit more detail on expected outcomes would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 67% of parameters (repoId and ownerPubkey) with descriptions. The description adds the concept of 'owner+name' as an alternative to ID, which aligns with the schema but does not explain the 'relays' parameter. This provides marginal value beyond the schema, but the gap on relays prevents a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get'), a clear resource ('a single repository'), and explicitly states the two identification methods (by ID or owner+name). This immediately distinguishes it from siblings like listRepos (multiple repos) and searchRepos (search behavior), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when you need one repository and you have its ID or owner+name. It does not explicitly mention alternatives or when not to use it, but the phrasing 'a single repository' naturally contrasts with listing/searching tools, giving implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions publishing NIP-82 events and the need for an ok:true + hashed APK payload, but doesn't disclose side effects like network writes, signing with privkey, failure behavior, or return values. For a publish operation with zero annotation support, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, entirely front-loaded, no wasted words. The first sentence delivers the core behavior, the second provides clear prioritization guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters, no output schema, and no annotations, the description is far too terse. It doesn't explain return values, error conditions, or the meaning of most parameters. It does provide some context about being low-level, but that alone doesn't make the tool safely invocable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 9% (only 'forge' has a description). The description adds a minimal hint about the forge payload (ok:true + hashed APK) but says nothing about the other 10 parameters including the required 'privkey'. It does not compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool publishes NIP-82 events from an already-fetched forge payload, naming the specific protocol and prerequisite. It distinguishes itself from sibling announceSoftwareFromForgeRelease by labeling itself 'Low-level' and directing users to prefer the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Low-level' and 'Prefer announceSoftwareFromForgeRelease', giving clear when-to-use vs alternative guidance. Also implies prerequisite of having an already-fetched forge payload from fetchForgeReleases.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the HTTP method (POST), authentication requirements (lnbits credentials), and the post-payment action of publishing to Nostr. However, it does not disclose side effects on the bounty, whether the operation is idempotent, or what happens on failure. The description adds useful context but lacks important behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences long, and front-loaded with the main action. Every sentence adds valuable information: the endpoint, credentials, and the follow-up Nostr publication. There is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity with a payment flow and a Nostr publishing step, and there is no output schema. The description covers the main action and the post-pay step, but it does not explain the expected return value (e.g., invoice details, payment request), how payment status is checked, or error scenarios. For an agent to use this tool effectively and handle the follow-up, more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the optional credential parameters (lnbitsUrl, lnbitsAdminKey) and mentions env var alternatives, but it does not explain the required parameters (issueId, amount) or what values they should take (e.g., amount in satoshis). The description gives only partial parameter guidance, leaving the most critical inputs ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a Lightning invoice for bounty escrow, giving a specific verb and resource. It also provides the endpoint (POST /api/bounty/create), which precisely defines the operation. This distinguishes it from sibling bounty tools like bountyRelease or submitBounty.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to create a Lightning invoice for bounty escrow) and gives instructions on authentication via env vars or passing credentials. It also mentions a follow-up action (publish via publishBountyToNostr after payment), which helps the agent understand the workflow. However, it does not explicitly mention when not to use it or compare with alternative tools.
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?
With no annotations provided, the description carries the burden. It discloses that credentials are auto-loaded from .nostr-keys.json and that the tool performs both file pushing and Nostr publishing. However, it omits return value behavior, error handling, and idempotency details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the primary action and benefit. The phrase 'Best for agents!' is slightly promotional but does not detract significantly. Each clause contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters) and lack of output schema, the description gives a clear high-level overview but does not explain what the tool returns or how it handles potential failures. It relies on schema descriptions for parameter details, which is acceptable but leaves gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers most parameters with descriptions (90% coverage). The description adds minimal parameter-specific insight beyond noting auto-loading of credentials, which relates to the privkey parameter. It does not compensate for the small coverage gap or explain parameter interactions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'CREATE A REPO' and clearly states the scope: pushing files and publishing to Nostr. It distinguishes itself from sibling tools like createIssue or pushToBridge by combining operations into one call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the primary use case: creating a repo with files in one call, and notes it's 'Best for agents!' It does not explicitly name alternative tools or state when not to use it, but the context of a one-call combined operation is 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?
With no annotations, the description carries the full burden. It discloses the internal Nostr event mechanism (kind 7 with #k 30617) and the 'latest reaction per repo wins' rule, adding meaningful behavioral context. It does not mention side effects, but 'list' implies a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence, front-loaded with the main action and followed by a compact parenthetical with technical details. There is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives the core purpose and some technical context, but lacks an output format description and does not explain the relays parameter. With no output schema and no annotations, the description is adequate for an expert but leaves gaps for a general AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (relays is undocumented). The description adds no parameter information at all, leaving the relays parameter unexplained. It fails to compensate for the schema gap, even though the schema's pubkey description mentions auto-detection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists starred repos, using the specific verb 'List' and the resource 'repos a user starred'. It also adds technical detail about event kind and dedup logic, which distinguishes it from siblings like listWatchedRepos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing starred repos but does not explicitly compare with alternatives or state exclusions. It lacks guidance on when to choose this over listWatchedRepos or other list tools, leaving usage inferred from the tool name and phrasing.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses signed HTTPS auth, the merge/push process, conditional authorization logic, and optional Nostr events (30618+1631). It also notes the external dependency on git. However, it does not mention failure modes, conflict handling, or side effects on existing refs, leaving some behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action in a colon-separated phrase. It conveys multiple pieces of information (auth, merge steps, optional events, authorization, dependencies) in just a few sentences without excessive verbosity. Slightly dense but generally well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex operation with 8 parameters, no output schema, and no annotations, the description covers key aspects: the merge process, authorization rules, prerequisites, and optional parameters. However, it omits details about return values, conflict resolution, and exact effects of the Nostr events. The description is adequate but not fully complete for such a multifaceted tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 63%, so the schema already documents many parameters. The description adds value by clarifying that repoId is optional if derivable from the PR a-tag and implies privkey is used for signed auth. However, it does not explain relays, mergeMessage, or other undocumented parameters, leaving some parameters without semantic enrichment beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Full merge: git clone/fetch with signed HTTPS auth, merge PR head, push to bridge, optional 30618+1631.' This specifies the action (merge), the resource (PR), and the process, distinguishing it from siblings like pushToBridge or markPullRequestMerged. The verb 'merge' and the detailed steps leave no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides prerequisites: signer must be repo owner or maintainer, git must be on PATH, and repoId is optional if derivable from the PR a-tag. However, it does not explicitly state when to use this tool instead of related siblings like pushToBridge or markPullRequestMerged. The guidance is implied by the 'Full merge' label but lacks explicit alternatives or exclusions.
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 description discloses return value details (prefer git.gittr.space, multiple cloneUrls, relays for location-agnostic use) but carries the full burden since no annotations are provided. It does not mention whether the operation is read-only, requires credentials, or behaves on failure, leaving notable behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and every phrase contributes (identity, repo name, return values, location-agnostic rationale). There is no fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with no output schema and no annotations, the description covers the main purpose and return shape. However, the unexplained 'relays' input parameter and the potential confusion with output relays introduce a clear gap, making it less than fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, and the description adds little beyond the schema for ownerNpubOrHex and repoId. The 'relays' input parameter is entirely unexplained, and the description's mention of 'relays' in the output creates ambiguity about whether it is an input or output field. The description fails to compensate for the missing parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Resolve repo by Nostr identity (npub or hex) and repo name') and identifies the resource (repo) and distinguishing input type (Nostr identity). It also specifies the output (cloneUrl, cloneUrls, relays), making it unambiguous and distinct from siblings like listRepos or searchRepos, which focus on listings or queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: when you have a Nostr identity (npub or hex) and a repository name, this tool resolves the repository's clone URLs. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to know when to select this 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?
With no annotations, the description carries the full burden. It discloses the NIP-09 kind 5 mechanism and the non-deletion of the git repo, but omits behavioral details like auth requirements (privkey/ownerPubkey), whether deletion events are broadcast to relays, irreversibility, and ownership verification. Partial but not complete transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every phrase adds value: protocol, action, resource type, and an important exclusion.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool with 4 parameters, no output schema, and no annotations, the description is relatively thin. It does not explain return values, error conditions, relay usage, or whether ownership is required. It provides the core function but lacks operational context an agent would need for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only eventIds and privkey have descriptions). The description adds useful context that eventIds refer to NIP-82 app/release/asset events, but relays, privkey, and ownerPubkey are not elaborated on beyond the schema. It partially compensates for the gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs NIP-09 kind 5 deletion for previously published NIP-82 event IDs, specifying the resource types (app/release/asset) and explicitly noting it does not delete the git repo. This distinguishes it from sibling publish/announcement tools and repo deletion operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case for removing previously published NIP-82 announcements and explicitly excludes git repo deletion, which provides a clear boundary. However, it does not explicitly name alternative tools or conditions where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the source file and purpose but does not mention what the tool returns, whether it outputs sensitive credentials, or any side effects. Loading credentials could be security-sensitive, and this is not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the verb and resource. Every word contributes meaning, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description is mostly complete, but it lacks any mention of the output or return value. Since there is no output schema, the description should have indicated what 'loading' results in (e.g., returning credentials, setting environment variables), making this a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty with 100% coverage. Per the rubric, 0 params earns a baseline of 4 since there is nothing for the description to add about parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (Load), the resource (Nostr credentials), and the source (from .nostr-keys.json). The parenthetical '(for debugging)' adds context and helps distinguish this utility tool from the many repo/PR/bounty siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by noting 'for debugging', implying this tool is intended for debugging purposes. It doesn't explicitly name alternatives or exclusions, but given the unique nature of this tool among siblings, the usage context is sufficient.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal the underlying event structure (NIP-25 kind 7, tags e+k+p, content +) and the dependency on a published announcement, which adds transparency beyond the name. However, it omits effects like reversibility, failure behavior if no 30617 event exists, and any side effects on existing stars. The disclosure is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence front-loads the action and packs necessary protocol details into a parenthetical, while the second states the prerequisite. There is no filler or redundancy; every clause carries meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no annotations, no output schema), the description is relatively lean. It explains what the tool does and a key prerequisite, but does not describe return values, error cases (e.g., missing 30617 event), or behavior when the announcement is not found. For a mutation tool with no structured metadata, more completeness would be helpful; the description is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80% (4 of 5 params documented), so the baseline is 3. The description adds meaningful context by explaining the relationship between parameters: it states that it acts on the 'latest kind 30617 event,' which clarifies how repoId and ownerPubkey are used to locate the event. It also explains the prerequisite that the repo announcement must be published, giving further semantic context to the lookup parameters. This is valuable beyond the bare schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Star a repo' with a specific verb and resource. It further specifies the technical implementation (NIP-25 kind 7 on the latest kind 30617 event), distinguishing it from sibling tools like unstarRepo, watchRepo, and listStars. The purpose is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating 'Requires a published repo announcement on relays,' which is a clear prerequisite. However, it does not explicitly contrast this tool with alternatives (e.g., unstarRepo) or mention when not to use it. The usage is largely implied by the tool name and reputation, but no direct guidance is given.
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 description discloses the underlying Nostr event type and content, but with no annotations it must carry the full burden. It does not mention auth requirements (e.g., privkey), side effects on existing events, or return values, leaving important behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence. It front-loads the core action, includes necessary technical detail, and avoids any wordiness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description gives the essential action and event format, but lacks information on prerequisites, how the operation is executed (e.g., publishing to relays), or what happens after unstarring. This is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so parameters are mostly documented. The description adds that tags are the same as starRepo, providing some relational context, but it does not explicitly explain each parameter or add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Unstar a repo' with a specific verb and resource, and adds implementation details (NIP-25 kind 7, content '-') that distinguish it from sibling tools like starRepo, listStars, and watchRepo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage when a user wants to remove a star, and the reference to 'Same tags as starRepo' provides context about parameter reuse. However, it does not explicitly state when not to use it or provide alternatives, which would be clearer.
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?
No annotations are provided, so the description carries the burden. It discloses that the tool lists git tags from the bridge and not software releases, which sets expectations about the data source and scope. However, it does not mention read-only behavior, authentication needs, or the role of the 'relays' parameter, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and front-loaded with the verb 'List'. It includes a necessary qualifier about what it is not, without any redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description conveys the core function and a key distinction from related tools. It does not explain return format or relay usage, but the schema covers limit and default behavior. Given the lack of an output schema, the description is adequate but could mention the relays parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (3 of 4 parameters have descriptions). The description itself does not add parameter-level meaning beyond what the schema provides. The 'relays' parameter is left undocumented in both the schema and description, so the agent gets no clarification on its purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('git tags from the bridge (refs/tags/*)'), and explicitly distinguishes from 'Zapstore software releases'. This specificity differentiates it from sibling tools like createRelease or fetchForgeReleases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'not Zapstore software releases' clause provides a clear exclusion, guiding the agent to avoid this tool for software release operations. However, no alternative tool is explicitly named, so the guidance is clear on context but not fully explicit with alternative suggestions.
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?
With no annotations, the description carries the burden of disclosing behavior. It reveals fallback mechanics ('Tries gittr bridge file-content, then a few hardcoded GRASP /raw/ hosts'), a limitation ('Not full Code-tab parity'), and recomended workflow. However, it does not detail error behavior or return value beyond implicit content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose and includes necessary caveats. It is concise but slightly dense with internal jargon like '30617 clone[]', which might reduce clarity for some agents. Still, every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, no output schema, no annotations), the description covers purpose, usage context, and limitations. It does not describe return format, but that is largely implicit for a file-content tool and the sibling list provides additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter details (e.g., 'Path to file (e.g., "README.md")'). The description adds little parameter-specific meaning, mainly emphasizing the 'without full clone' approach. This aligns with the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Get file content without a full local clone.' It also distinguishes itself from siblings by mentioning the gittr bridge and GRASP hosts, and explicitly notes it is not full Code-tab parity, setting it apart from tools like bridgeListFiles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (when you need file content without a cache) and offers an explicit alternative: 'prefer bridgeListFiles after importRemoteToBridge/mirrorRepo.' It also implies limitations, but does not systematically exclude other 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?
With no annotations, the description carries the burden. It discloses auto-loading of .nostr-keys.json when privkey is omitted and specifies the event kinds (32267/30063/3063). However, it does not mention potential public write effects or reversibility, though 'announce' and 'catalog' imply a public write.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, information-dense sentences. Each sentence adds value: the action, the analogy to a known UI, and a key behavioral note. No redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no output schema, the description provides the core workflow and key behavioral context. It does not describe return values or edge cases, but the high schema coverage and clear purpose make it sufficiently complete for tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 91%, so the schema already documents most parameters. The description adds only a note about privkey fallback which is also covered in the schema. It does not explain additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool announces an Android app to a Zapstore/NIP-82 catalog from a forge Release APK, specifying event kinds and referencing the gittr Code sidebar action. This specific verb+resource combination distinguishes it from sibling tools like publishSoftwareAnnounce or publishRepoAnnouncement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Same as gittr Code sidebar Announce app' provides clear contextual usage, implying this tool replicates that UI action programmatically. It does not explicitly state when not to use it or name alternatives, but the source (forge Release APK) makes the intended scenario clear.
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?
With no annotations, the description carries the burden of behavioral disclosure. It adds useful safety context ('never returns private key', 'hex/npub only'), but does not mention output shape, possible errors, or side effects. This is adequate for a simple status check but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core purpose and followed by essential usage and safety notes. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, simple status tool, the description provides purpose, format, security, and usage ordering. However, with no output schema, it doesn't explicitly state whether the tool returns a boolean, string, or object, nor what happens if keys are not loaded. The implicit 'whether' covers this partially, but a small gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the baseline is 4 per the rubric. Schema coverage is 100% (empty schema), and the description adds no param-specific detail, which is appropriate given there are no parameters to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Show' and names the resource 'Nostr keys', with explicit scope 'whether keys are loaded'. It also distinguishes itself from sibling tools by specifying the hex/npub format and the 'never returns private key' safety qualifier, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to 'Use first in a session', giving clear timing/order context. It does not explicitly name alternatives or exclusions, but the session-first guidance effectively differentiates it from tools like loadCredentials or getPublicKey.
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?
With no annotations provided, the description carries the transparency burden. It discloses that hash:true is slow and required before announce, adding behavioral context beyond the schema. However, it does not mention potential failures, rate limits, or whether the operation is read-only, so it is not fully 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two succinct sentences. The first sentence states the core purpose, and the second provides a key usage caveat. No filler or redundant information, earning a maximum score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema) and lack of annotations, the description covers the main purpose and a critical usage requirement. However, it does not explain the return structure or how it fits with siblings like announceSoftwareFromForgeRelease beyond the 'required before announce' hint, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 adds extra nuance by explaining the hash parameter's role ('slow; required before announce') and clarifies sourceUrl supports GitHub/Codeberg/GitLab forges, which provides value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Fetch latest public forge Release') and resource (external forges: GitHub/Codeberg/GitLab) along with APK assets. This distinguishes it from sibling tools like listReleases by focusing on external forge releases and asset fetching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the hash parameter: 'required before announce'. It implies this tool is a prerequisite for announcing releases, but it does not explicitly name alternative tools or state when not to use it. This warrants a 4 rather than 5.
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?
With no annotations, the description carries the full burden, and it discloses the auth requirement ('REQUIRES signing with privkey'), destructive deletion behavior ('removes files or whole folders'), and the default of allowTreeShrink. It stops short of describing the commit/response behavior, but covers key traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core function and auth, followed by optional behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers the essential push, auth, delete, and tree-shrink semantics. It lacks output/return behavior and conflict handling, but with 8 params and no annotations, it gives adequate context for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description emphasizes privkey requirement and clarifies deletedPaths and allowTreeShrink interaction, but most param meaning is already in schema, so limited additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Push files to git server' with a specific verb and resource. It also notes the signing requirement and optional deletion behavior, distinguishing it from read-only sibling tools like bridgeListRefs and getFile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for pushing files to a git repo and notes the requirement for privkey signing. It does not explicitly exclude alternatives, but the unique 'push' operation among siblings provides clear context. The deletion and tree-shrink behavior gives additional guidance on when to use these options.
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?
With no annotations provided, the description carries the burden of disclosing behavior. It clearly states that it performs exact matching, scans kind-30617 announces, returns npub and gittr URL, and does not fuzzy-match. It omits details like authentication requirements or rate limits, but as a read-only lookup, the disclosed information is reasonably sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose ('Exact reverse lookup'), followed by the return value and use case, and ending with a critical limitation. Every sentence contributes meaning, with no redundant or tangential content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core purpose, return value (npub + gittr URL), and a key constraint (no fuzzy matching), while parameter details are covered by the schema. It does not describe error cases or pagination behavior, but for a reverse lookup tool with a clear schema, the context is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a descriptive definition. The description adds semantic value by clarifying the exact matching intent for the 'source' field, indicating that both forge URLs and GitHub shorthand are accepted, and emphasizing the exact-match behavior, going beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately identifies the tool as an 'Exact reverse lookup' and specifies what it matches: forge URLs or GitHub shorthand to find Nostr kind-30617 announces. It clearly distinguishes itself from similar sibling tools by emphasizing exact matching, supporting multiple forge types, and explicitly noting it does not fuzzy-match renamed slugs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case ('so you can DM owners when the forge is unreachable') and states it is for exact reverse lookup, implying a different purpose than search or fuzzy matching. However, it does not explicitly name alternative tools like searchRepos or findReposByGithub, so the 'when-not-to-use' guidance is implicit rather than direct.
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?
With no annotations provided, the description carries the full burden of disclosure. It openly states the side effect of writing .nostr-keys.json, the permanence of a keypair, the requirement for confirm:true, and the guardrail against overwriting real credentials without force:true. This is thorough and leaves no critical behavior hidden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: main purpose, user-consent requirement, and overwrite protection. The use of caps for 'ASK THE USER FIRST' and the clear conditional statements keep it tight and scannable with zero fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (file write, identity implications) and the absence of annotations or an output schema, the description is remarkably complete. It covers the side effect, the safety requirements, and the auto-load behavior, leaving no major gaps for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters with descriptions, so the baseline is 3. The description adds value by linking the parameters to the user-consent flow: confirm must be true after explicit agreement, and force only applies when the user asked for a fresh test identity. This enriches the meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Create a disposable TEST Nostr keypair and write .nostr-keys.json'. It clearly distinguishes the tool from siblings like loadCredentials or getPublicKey by emphasizing the disposable test nature and the auto-load side effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when/when-not guidance: 'ASK THE USER FIRST' and 'Never overwrites real credentials unless force:true'. It does not name alternative tools, but the consent flow and force behavior are clearly specified, which is stronger than merely implying context.
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:

[![gittr-mcp MCP server](https://glama.ai/mcp/servers/arbadacarbaYK/gittr-mcp/badges/card.svg)](https://glama.ai/mcp/servers/arbadacarbaYK/gittr-mcp)

Score Badge

Copy to your README.md:

[![gittr-mcp MCP server](https://glama.ai/mcp/servers/arbadacarbaYK/gittr-mcp/badges/score.svg)](https://glama.ai/mcp/servers/arbadacarbaYK/gittr-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/arbadacarbaYK/gittr-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server