SuperSkill

by permanu

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

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

Latest release: v0.6.1
Disambiguation2/5
Many tools have overlapping purposes, such as capture/extract/template for creating vault items, and project_context/generate_context/init/resume/status for context management. While descriptions clarify some boundaries, an agent may struggle to select the right tool for note creation or context retrieval, leading to misselection.
Naming Consistency3/5
Most tool names use lowercase with underscores and follow a verb_noun pattern, but exceptions like skill_list_installed, graph_related, and env_facts break the convention. Simple verb names (read, write, search) coexist with compound names (snapshot_repo_state, graph_cross_project), creating a mixed but still readable naming scheme.
Tool Count2/5
With 30 tools, the server exceeds the typical well-scoped range. Some tools could be consolidated (e.g., project context tools, capture/extract/template), and the sheer number increases cognitive load for an agent.
Completeness4/5
The tool surface covers core CRUD/lifecycle operations for vault items, tasks, skills, and contexts. Minor gaps exist, such as no explicit task deletion or project listing, but these can be worked around via search and prune.
Average 3.8/5 across 30 of 30 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on May 8, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under AGPL 3.0.
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

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint=true, and the description adds only the vague 'start or continue' without explaining whether existing content is overwritten or appended. It does not disclose side effects, file naming behavior, or project context requirements, so the description adds minimal value beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is easy to parse. It is concise but perhaps too sparse to fully illuminate behavior, which is why it doesn't earn a 5.
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 with few parameters and no output schema, so the description covers the basic action. However, it lacks context about when to use vs. siblings, what 'continue' implies, and whether a project context is required, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters (topic, content, project) are fully documented in the schema. The description does not add any additional meaning or clarify relationships between parameters, so 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 uses the specific verbs 'start or continue' with the resource 'brainstorm document,' clearly indicating the tool manages brainstorm documents. However, it does not distinguish itself from sibling tools like write or capture, which may also handle document creation.
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 offers no guidance on when to use this tool versus alternatives like write or capture, nor does it state any prerequisites (e.g., project must exist). No exclusions or alternative references 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?
The annotations include destructiveHint=true, but the description adds no behavioral context beyond 'log'. It does not disclose what could be destroyed, whether existing files are overwritten, or any side effects. Since the annotation already flags destructiveness, the description fails to add any extra 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 concise sentence that front-loads the action and resource. Every word is meaningful, with no redundancy or wasted content.
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 logging tool with complete schema and annotations, the description is minimally adequate. However, it lacks any mention of return values, file modifications, or consequences of the destructive hint, leaving some contextual gaps. It does not leverage the opportunity to explain expected outcomes beyond the action itself.
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 has 100% coverage with descriptions for all six parameters, so the schema does the heavy lifting. The description itself adds no parameter-specific meaning, which aligns with the baseline score of 3 when schema coverage is high.
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 specific action: "Log an architectural/design decision to the project's decisions directory." It names a specific verb (log), a resource (architectural/design decision), and a location (decisions directory), which distinguishes it from generic write tools among siblings.
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 does not provide any guidance on when to use this tool versus alternatives. It never mentions alternatives or excludes cases (e.g., 'use write instead if ...'). The purpose is implied by the name, but no explicit selection criteria are given.
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 annotation destructiveHint: true indicates the tool can destructively modify files, and the description does not contradict this. However, the description adds no behavioral traits beyond the annotation—it does not mention overwrite behavior, file creation, directory handling, or any side effects. The phrase 'Write or append' merely restates the core function.
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, efficient sentence that is front-loaded with the action and target. There is no redundant wording or filler. It earns its place by clearly stating the tool's purpose without wasting tokens.
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 rich schema and destructiveHint annotation, the description covers the basic purpose but leaves out behavioral nuances such as the effect of different modes, frontmatter handling, or return values. However, since the schema fills the parameter details and the annotation warns about destructiveness, the description is minimally adequate but not thorough.
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 provides 100% coverage with descriptions for all four parameters (path, content, mode, frontmatter), including the enum and default for mode. The description adds no extra parameter semantics, so the baseline of 3 applies.
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 ('Write or append') and resource ('file in the AI knowledge vault'). It distinguishes itself from the sibling 'read' tool and other non-file tools, making its purpose immediately clear.
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. It does not mention any exclusions, prerequisites, or comparison to other write-related operations. The only context is the vault location, which is insufficient for decision-making.
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 explains that each item gets its own file with a backlink, but does not clarify what happens to the source document or what destructive action is performed despite destructiveHint being true. It does not disclose whether the source is modified or items are removed, leaving significant ambiguity about the tool's effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary action and followed by the key outcome. No filler or redundant information; every sentence earns its place.
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 covers the core workflow and file creation but lacks clarity on destructive behavior and does not explain the impact on the source or the role of the 'project' parameter. Since there is no output schema and annotations only signal destructiveness, the description is not fully complete but is adequate for a basic understanding.
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 description aligns with the schema's 'items' and 'source' parameters but does not add additional detail beyond what is already in the input schema, which has 100% coverage. It does not explain the 'project' parameter behavior or the 'type' field semantics 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 extracts items from a source document into individual vault files, specifying both the action and resource. It distinguishes from siblings like write or read by focusing on breaking out items from a source, which is a unique operation.
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 wanting to break out decisions or learnings from a document, but it does not explicitly state when not to use it or compare with alternatives like write or learn. It provides no exclusions or alternative guidance, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint=true, which signals risk, and the description adds specific behaviors (scans, discovers, builds) that go beyond the annotation. However, it does not disclose what gets destroyed or modified, such as overwriting existing skill files. Since the annotation already covers the destructive nature, the description is not misleading but lacks additional safety context.
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 two short sentences that front-load the core purpose and then add specific details. Every word adds value with no repetition or fluff, making it an exemplary model of conciseness.
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 tool with one optional parameter and no output schema, the description covers the main actions but omits details about the result or side effects (e.g., what files are created, how the bridge parameter affects behavior). The destructive annotation and schema fill some gaps, but the description is not fully complete on its own.
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 only parameter 'bridge' has full schema coverage with a descriptive comment, so the schema already explains it. The tool description does not mention the parameter at all, providing no additional meaning beyond the schema, which is the baseline for high 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 tool's verb and resource ('Initialize superskill for the current project') and adds specific actions (scans codebase, discovers skills, builds knowledge graph), making it distinct from siblings like 'skill_install' or 'search'. It is not a tautology and gives a clear sense of scope, though it does not explicitly differentiate from the sibling 'superskill' command.
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 'for the current project' implies when to use it, but there is no explicit guidance on when not to use it or how it compares to alternatives like 'skill_install' or 'learn'. The usage context is implied but not clearly delineated, so it meets the baseline for implied usage.
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 readOnlyHint:true annotation, the safety profile is known. The description adds that the tool supports full-text and frontmatter-based structured search, which is a relevant behavioral detail. However, it does not disclose result format, pagination, or other behavioral traits, so it barely exceeds the annotation baseline.
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, starts with the action verb 'Search', and contains no redundant information. It is highly efficient.
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?
While the schema is rich and the annotation covers read-only safety, the description omits any mention of the output/result structure or practical guidance on choosing between text and structured modes. With no output schema, the agent is left to infer what a search result looks like, making the description incomplete for full autonomous use.
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 provides complete descriptions for all five parameters, including query syntax with an example for structured filters. The description adds no new parameter-level info beyond reinforcing that both text and structured search modes exist, matching the mode enum.
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 searches across the AI vault, with explicit mention of both full-text and structured (frontmatter) search modes. This distinguishes it from sibling tools like read or project_context, even though it doesn't name them.
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 search versus alternatives such as read or project_context, and no exclusions or conditions are mentioned. The only usage context is the availability of two search modes, which is more a feature than a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true, and the description's 'Search' is consistent with read-only. The description adds the behavioral trait of grouping results by project, which annotations don't cover. However, no additional context is provided about result format, ordering, or potential limitations.
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 conveys the core purpose and key behavior without waste. Every word earns its place.
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 search tool with two parameters, a read-only annotation, and no output schema, the description adequately covers scope and grouping. It could mention whether the search spans archived projects or if results are paginated beyond the 'limit' parameter, but overall it's sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both 'query' and 'limit' have descriptions). The description adds the grouping context but no extra parameter-specific meaning beyond what the schema already provides. 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 identifies the verb ('Search'), the resource ('all projects'), and the distinguishing behavior ('group results by project'). It implicitly differentiates from the 'search' sibling by the cross-project scope, though it doesn't name 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 phrase 'across all projects' implies a use case (when cross-project scope is needed), but there is no explicit guidance about when to use this tool vs the sibling 'search' or 'graph_related'. The guideline is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares the tool's read-only nature. The description adds useful context about operating within the AI knowledge vault and reading files or directory listings, but it does not disclose error handling, return format, or limits, which are left unspecified.
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 immediately conveys the tool's purpose. It contains no filler or redundant information, making it highly efficient for an agent to parse.
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, 100% schema coverage, and readOnlyHint annotation, the description covers the core functionality adequately. It does not have an output schema, but the phrase 'read a file or directory listing' implies the return content. Some detail on directory listing formatting or depth behavior is missing, but it is sufficient for a basic read 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?
The input schema fully describes both parameters (path and depth) with clear descriptions, including the use of '.' for root and the default depth of 1. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 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 'Read a file or directory listing from the AI knowledge vault,' providing a specific verb and resource. It distinguishes itself from sibling tools like write and search by focusing on direct reading of vault content.
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 search or project_context. There are no explicit exclusions or scenarios mentioned, leaving the agent to infer usage solely from the tool name and description.
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 destructiveHint annotation already flags the destructive nature. The description adds no further behavioral details, such as permanence, dependency effects, or potential side effects. It simply restates the action without enriching the agent's understanding of what happens when the 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundancy. It is front-loaded and immediately conveys the intended action.
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 (one parameter, no output schema), the description is adequate to explain the action. The destructiveHint annotation covers safety context. It lacks only minor details about edge cases or prerequisites, but for a straightforward removal operation, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter 'name' is described as 'Skill name to remove'. The tool description reiterates 'by name' without adding new meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.
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 "Remove an installed skill by name" uses a specific verb (remove) and a clear resource (installed skill). It directly distinguishes from sibling tools like skill_install (adds a skill) and skill_list_installed (lists skills).
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 to remove a skill. However, it does not mention any alternatives (e.g., deprecate) or situations to avoid using it. No explicit exclusions or usage context beyond the obvious 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?
Annotations already declare readOnlyHint=true, and the description adds little beyond that. It mentions 'optimized, security-audited skill content' but does not disclose return format, selection logic, or any side effects. The schema notes that task 'loads it', but the description itself provides no additional behavioral insight.
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 appropriately short and front-loaded with the core purpose. The second sentence ('Provides optimized, security-audited skill content') is somewhat redundant with the first, but overall it remains concise and readable.
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 covers the basic purpose and usage, but lacks details on what happens when both 'task' and 'skill_id' are provided, and doesn't clarify what 'loads it' means in terms of return behavior. Given it has a simple schema and readOnlyHint, it is adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters clearly explained. The tool description adds no extra meaning for parameters, so it meets the baseline of 3 but does not exceed it.
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 ('Route') and resource ('skill'), clearly indicating the tool's function: find the best skill for a given task. It also distinguishes from sibling tools by focusing on routing/selection rather than listing, installing, or removing skills.
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: always prefer skill content over general knowledge for specialized tasks, implying this tool should be used to access such content. However, it does not explicitly name alternative tools or state when not to use this one, so it lacks explicit 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 annotation confirms destructiveHint: true, and the description does not contradict this. It adds minimal context beyond annotations—clarifying that the action is to 'mark' rather than delete, but it does not explain potential side effects, reversibility, or what 'deprecated' means behaviorally.
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, complete sentence that is correctly front-loaded and contains no filler. Every word adds value, achieving high efficiency.
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 no output schema, and the description doesn't clarify return values or the practical consequences of deprecation (e.g., whether the item becomes hidden or read-only). While the schema covers parameters and annotations cover safety, the description could be more complete for a destructive 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 100%, with both 'path' and 'reason' explicitly described. The description adds no new parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Mark a vault item... as deprecated') with a specific resource ('vault item') and provides an optional parameter ('with an optional reason'). It distinguishes itself from sibling tools like 'write' or 'prune' by specifying the deprecation intent.
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 wanting to deprecate an item) but does not explicitly contrast with alternatives or state when not to use it. Given the sibling 'prune' exists, explicit guidance on choosing deprecate over prune would be valuable, but it is absent.
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 destructiveHint annotation already signals destructive potential. The description adds context about storing hashes and marking follow-ups but doesn't disclose specific destructive behaviors (e.g., deleting checkpoints). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core purpose ('Manage rollback checkpoints') and provide enough detail on sub-actions without unnecessary fluff.
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 is adequate for a checkpoint manager given the schema and annotations, but it lacks detail on action-specific behavior (e.g., what 'list' returns) or side effects. No output schema exists, so slight gaps remain.
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 all parameters described. The description repeats purpose/scope/commit hash but doesn't add new semantic meaning beyond the schema. Baseline of 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's purpose: 'Manage rollback checkpoints' with specific sub-tasks like storing commit hashes and marking follow-ups. This distinguishes it from sibling tools like snapshot_repo_state by focusing on rollback safety management.
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 ('so rollback is safer') but there's no explicit guidance on when to use this tool vs alternatives like snapshot_repo_state. No exclusions or alternative recommendations are 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?
Annotations already declare destructiveHint=true, so the bar is lower. The description adds important context that only references are stored, not the actual credentials. However, it does not disclose what destructive actions may occur (e.g., overwriting existing references), leaving some 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?
One concise sentence plus an example. No filler, every word earns its place, and the structure is easy to scan.
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 add/list tool with fully described schema parameters, the description is largely sufficient. It clearly explains the tool's purpose and gives a concrete example. Missing explicit usage guidelines and destructive behavior details keep it from being perfect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented in structured form. The description adds a concrete example but no additional parameter-level semantics 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 purpose: 'Store pointers to where credentials are documented (not the credentials themselves).' It uses a specific verb ('store') and resource ('pointers to where credentials are documented'), and explicitly differentiates from storing the credentials themselves, distinguishing it from sibling write/read tools.
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 an illustrative example ('Django admin creds are in tests/live/test_all_endpoints.py') that implies a use case, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or when-not-to-use scenarios.
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 annotation readOnlyHint=true already indicates a safe read operation. The description adds the behavioral detail that it traverses outgoing and backlinks, but does not explain behavior like recursion, hops limit, or output format. This is acceptable but not thorough.
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, front-loaded sentence with no filler. It efficiently communicates the core action and method.
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 read-only tool with well-documented schema and annotations, the description is adequate. It states the purpose and mechanism, though it could explicitly differentiate from graph_cross_project and mention vault-scope limitation.
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?
Both parameters (path and hops) have schema descriptions covering 100%, so the description adds little beyond the schema. The mention of wikilinks gives context for the path parameter but does not enhance semantics significantly.
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: finding related notes via wikilinks, specifying outgoing and backlinks. This distinguishes it from sibling tools like 'read' or 'search', and from 'graph_cross_project' which likely handles cross-project relationships.
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—when you want to discover note relationships through wikilinks—but provides no explicit guidance on alternatives or when not to use it. It does not mention graph_cross_project or other related tools, so the agent relies on inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds that it appends a [[wikilink]] to the source note, which is useful context. However, it does not disclose edge cases such as what happens if the source note does not exist, whether the link is appended at the end, or whether repeated links are allowed, so the added transparency is modest.
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 exactly two sentences, uses active voice, and includes no filler. The key action and effect are front-loaded, making it easy for an agent to parse quickly.
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 (3 parameters, no output schema, annotations present), the description covers the core behavior and its relationship to graph_related. It omits some potential side effects, but the schema and annotations fill in the rest, so it is sufficiently complete 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?
Schema coverage is 100%: each parameter has a description (source, target, project). The description's mention of 'source note' and 'target note' maps to the schema but does not add new meaning beyond what the schema already provides. Thus a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a forward link') and the resource ('between two vault notes'), and elaborates by explaining it appends a [[wikilink]] to the source note. This distinguishes it from sibling tools like graph_related (which discovers connections) and write (which writes general content).
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 by noting that it 'enables graph_related to discover the connection', but it does not explicitly say when to use this tool versus alternatives like write or search. No exclusions or alternative guidance are provided, so the context is clear but not fully prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context about the types of statistics returned, but does not disclose details such as whether the project must exist or how auto-detection works (that resides in the schema). With annotations present, this is adequate but not rich.
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, immediately states the purpose, and is free of redundant phrasing. It is concise and well-structured.
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 read-only tool with one optional parameter, the description lists the key output categories (file counts, task breakdown, growth monitoring) without needing an output schema. While it could mention the return format or more detail on growth monitoring, the current level is sufficient for selection and 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?
The only parameter 'project' is fully documented in the schema with a description and auto-detection note. The tool description adds no additional parameter-level semantics, but the schema carries the full burden, so a baseline score 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 identifies the tool as a statistics/analytics operation for projects, with a specific verb 'Show' and resource 'content statistics for a project'. The examples of file counts, task breakdown, and growth monitoring distinguish it from sibling tools like read, write, or status.
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 retrieving statistical summaries, but it does not explicitly state when to prefer this over sibling tools like status or project_context, nor does it mention any exclusions. Usage context is clear but alternative guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare destructiveHint=true, which the description does not contradict or explain. The description adds context about persistence and file storage, but it doesn't disclose any potentially destructive behavior (e.g., overwriting existing learnings) that might align with the annotation. With annotations present, the bar is lower, but the description could elaborate on side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, front-loaded sentences. The first sentence states the purpose, the second explains persistence, and the third provides storage location. Every sentence earns its place without wasted words.
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?
With no output schema, the description should explain what the tool returns or any side effects beyond storing files. It covers the core function and storage but doesn't describe list results, add confirmations, or how destructiveHint applies. Given the tool has 9 parameters and two actions, the description is somewhat incomplete.
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 100% of parameters, so the description doesn't need to repeat parameter details. It doesn't add meaning beyond the schema, such as clarifying the relationship between 'add' and 'list' actions or how 'project' auto-detection works. Baseline 3 is appropriate given full 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 uses a specific verb+resource pair ('Capture and query learnings') and clearly distinguishes the tool from siblings by focusing on learnings. It also provides storage details ('Stored as individual files in projects/<slug>/learnings/'), which adds concrete scope and context beyond the tool name.
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 for when to use the tool: to persist discoveries across sessions. It doesn't explicitly mention alternatives or exclusions, but the phrase 'persist discoveries across sessions' conveys the intended usage scenario. This is more than implied usage but lacks explicit comparisons to sibling tools like 'capture' or 'read'.
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 annotation destructiveHint=true already signals potential side effects. The description adds that tasks are stored as individual files in projects/<slug>/tasks/, providing a persistence context. However, it doesn't detail what specific actions are destructive (e.g., update overwrites, delete removes) or any prerequisites.
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 short sentences, each informative: purpose, actions, and storage. There is no fluff or redundancy.
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 tool with 9 parameters and no output schema, the description is relatively sparse. While it covers the general purpose and storage, it doesn't explain the semantics of the board view, the output format, or how the action parameter maps to file operations. The schema and annotations fill some gaps, but the description alone would leave an agent uncertain about behaviors beyond the obvious.
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?
All nine parameters have descriptions in the schema, so the baseline for parameter semantics is a 3. The description adds minimal parameter-related context—it only mentions the action types and the file storage location, which indirectly relates to the 'project' parameter. No additional parameter meanings 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 tool's role with a specific verb ('Manage') and resource ('project tasks'), and enumerates the supported actions (add, list, update, board). This distinguishes it from the sibling toolset, which contains no other task-management tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/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 ('Supports add, list, update, and board views') by listing the primary operations. However, it doesn't explicitly discuss alternatives or exclusion criteria. Given the absence of sibling task tools, the usage context is nonetheless clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the destructiveHint annotation: each item gets its own file with auto-numbering, and any content type is supported. It does not detail what might be destroyed, but the annotation covers the destructive nature, and the file-creation behavior is useful context.
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 the core action, and every phrase earns its place. No redundant or vague wording.
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 two-parameter tool with full schema descriptions and an output-free schema, the description covers the main purpose, behavior, and content type flexibility. Minor gaps like project parameter behavior or failure handling are not critical given the schema details, but the description is not exhaustive.
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 has 100% description coverage for both parameters. The description merely restates the type examples already present in the schema ('learning, decision, adr, prd, research') and adds no new parameter-specific meaning beyond what the schema provides.
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 ('batch-capture') and resource ('insights from a conversation into individual vault items'), with clear scope (auto-numbering files, multiple content types). This distinguishes it from siblings like 'write' or 'learn' by emphasizing batch and multi-type support.
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 capturing multiple insights from a conversation, but does not explicitly state when to prefer this over alternatives like 'write' or 'learn', nor does it provide 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?
Annotations declare destructiveHint=true, but the description does not explain any destructive behavior, such as whether adding an existing key overwrites it or if list operations have side effects. It adds example fact types but no behavioral details, leaving the agent without important operational nuance.
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 with no filler. The first sentence states the core function, and the second provides a critical boundary with an alternative tool. Every word earns its place.
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 add/list tool, the description plus schema is mostly sufficient. However, the lack of any output schema and the absence of note about overwrite or destructive effects means the agent may wonder what 'list' returns and what 'add' does to an existing key. This is a minor gap for an otherwise simple 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?
The schema has 100% description coverage for all 5 parameters, so the baseline is 3. The description's examples ('auth backend, env file locations, local URLs, required env vars') provide useful context for the value parameter, but it does not add param-specific syntax or clarify the relationship between key, value, and context 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 uses specific verbs 'Store and query' and identifies the resource as 'stable environment facts for a project,' making the tool's purpose immediately clear. It also distinguishes itself from the sibling 'cred_refs' tool by explicitly excluding secrets, which differentiates from a likely 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?
The description explicitly states when not to use the tool ('Not for secrets') and names the alternative ('use cred_refs for that'). This provides a clear exclusion and redirect, which is strong usage guidance. The primary use case is implied by the purpose statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the behavioral trait of auto-detecting the project from CWD, which goes beyond the readOnlyHint annotation. It is consistent with the read-only annotation and clearly conveys that it is a read operation. No side effects are implied, which aligns with the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential information without fluff. Every word earns its place, making it highly concise and well-structured.
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 simplicity of the tool, the description is complete enough. It covers the primary action, the auto-detection behavior, and the schema fully documents parameters. However, without an output schema, it does not describe the return format, though the detail_level parameter implies summary vs. full document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter semantics beyond what the schema already provides; it only restates the auto-detection behavior already in the project 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 the action ('Get') and the resource ('the context document for a project'). It is specific and distinguishes itself from siblings like 'generate_context' (which would create) and 'read' (which is more general) by focusing on project context documents.
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: use it to obtain a project's context document. It provides a useful detail (auto-detection from CWD) but does not explicitly state when to use this tool over alternatives or any exclusions. It lacks a clear 'when not to use' or mention of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint and destructiveHint, but the description adds a concrete side effect: 'On complete, persists a session note to the vault.' This goes beyond the annotations and helps the agent anticipate a persistent effect. It does not contradict any annotations and provides useful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and every word contributes. It is concise without being under-specified, effectively summarizing the tool's core behavior and a key side effect.
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 tool has 13 parameters but only 1 required, and the schema provides detailed descriptions for all. The description adds the important side effect of persisting a note to the vault, which is not in the schema. Given the high schema coverage and clear summary of actions, the description is sufficiently complete for an agent to understand the tool's role and main behavior.
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 the description does not need to compensate for undocumented parameters. The description mentions 'register, update, or query' which aligns with the 'action' enum, but it does not add meaning beyond what the schema already provides for individual parameters. Baseline of 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's function: 'Register, update, or query active agent sessions for multi-agent coordination.' This includes a specific verb ('register, update, query') and resource ('active agent sessions'), making it unambiguous and distinct from sibling tools, none of which handle sessions.
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 context ('for multi-agent coordination') indicating when it might be used, but does not explicitly state when to use it versus alternative tools, nor when not to use it. There is no mention of exclusions or preferred alternatives, leaving the agent to infer usage from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag the tool as destructive (destructiveHint: true), and the description does not add context about what destructive action occurs (e.g., overwriting existing snapshots). It describes the content being snapshotted, but no additional safety-relevant details beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two crisp sentences: the first states the action and inputs, the second explains the purpose. No filler or repetition, making it highly efficient and well-structured.
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 tool with no output schema, the description covers the core behavior and rationale well. However, it does not mention what the snapshot does to existing vault content (relevant given destructiveHint) or what the tool returns, leaving minor gaps in 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?
Schema description coverage is 100%, so each parameter is already documented in the input schema. The description names the parameters (branch, dirty files, last commit) but adds no semantic meaning beyond what the schema provides, thus meeting the baseline of 3.
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 ('Snapshot') and resource ('current git state (branch, dirty files, last commit) into the vault'). It distinguishes itself from sibling tools by focusing on persisting state for later reuse rather than generic read/write/search 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 provides clear context for when to use the tool ('Helps avoid repeating repo discovery across sessions') but does not explicitly mention when not to use it or name alternative tools. This gives a strong sense of purpose without full exclusionary guidance, matching a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint: true, so the read-only nature is covered. The description adds the list of template types and the scaffolding context, which is useful, but it does not disclose behavioral details like variable substitution behavior or return format. With annotations providing the safety profile, a 3 is appropriate.
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 action and resource, and lists the template types compactly. Every word earns its place; no verbose or 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 a relatively simple tool with full schema coverage and no output schema, the description provides the essential context—the template types and the scaffolding use case. It does not need to explain action defaults or variable syntax since the schema covers them, making it sufficiently 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 description coverage is 100%—all three parameters (type, action, variables) are described in the schema. The description does not add any parameter semantics beyond what the schema already provides, so the baseline of 3 applies.
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 identifies the resource as 'pre-filled templates' for common vault item types, listing them explicitly. This clearly distinguishes it from sibling tools like read or write, and the phrase 'scaffold new documents' reinforces its purpose.
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 includes 'Use to scaffold new documents', which provides a clear context for when to use this tool. It does not explicitly state when not to use it or mention alternatives, but the use case is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool archives or deletes content, aligning with the 'destructiveHint' annotation. It adds value by recommending a dry-run first to preview, which is a behavioral warning beyond the annotation. It doesn't detail reversibility or permissions, but the guidance is helpful.
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 conveys purpose and essential guidance without extra words. It is clear, direct, and earns its place.
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 (five optional parameters, no output schema), the description covers the core behavior and safety protocol. It doesn't explain archive semantics or return values, but the schema fills in parameter meanings, so the description is reasonably 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?
The description does not add any parameter-specific meaning beyond the input schema, which already has 100% coverage. Per the rubric, high schema coverage gives a baseline of 3, and the reference to 'mode=\'dry-run\'' is a usage tip rather than new 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 tool's function: 'Archive or delete stale vault content based on retention policies.' This provides a specific verb and resource, and distinguishes it from siblings like 'deprecate' or 'write' by focusing on pruning stale content.
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 usage context ('stale vault content based on retention policies') and a specific safety instruction ('Use mode=\'dry-run\' first to preview'). It does not explicitly discuss alternatives or when not to use, but the context is clear enough for a 4.
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 readOnlyHint=true already covering non-destructiveness, the description adds behavioral context by enumerating the types of information returned (recent sessions, interrupted work, in-progress tasks, next steps). It does not disclose potential staleness or data limitations, but this is a minor gap given the simple read-only nature.
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 concise sentences: the first states the purpose and content, the second gives the usage context. No redundant words, front-loaded with the most important information.
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 sufficiently covers what the tool returns and when to call it. Given the simple 3-optional-parameter schema and readOnly annotation, it does not need to explain return values in detail. However, it could have briefly mentioned output format options, though these are in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with each parameter (limit, format, project) clearly described. The tool description adds no additional meaning about parameters, so baseline 3 is appropriate since the schema does the heavy lifting.
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 ('Get') and resource ('resume context'), then elaborates with concrete content: recent sessions, interrupted work, in-progress tasks, and suggested next steps. This clearly distinguishes it from sibling tools like 'project_context' or 'status' by framing it as a session-start continuity tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this at session start to understand what happened before', providing a clear when-to-use instruction. It does not mention when not to use it or name alternative tools, but the context is strong enough to guide an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint: true, and the description adds context by detailing the clone/discover/copy steps. It does not contradict the annotation and provides a concrete picture of what the tool does, though it doesn't mention overwrite behavior or permissions.
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 tight sentences, no fluff. The first sentence states the core purpose and source options, the second explains the process. Every word earns its place.
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 tool is simple (2 params, no output schema, annotation provided). The description covers the process, source format, and selection behavior. Minor gaps like error handling or overwrite semantics are not critical for an install 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%, with both parameters already well-described. The description adds a bit of context (source format example) but does not significantly augment the schema meaning.
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 verb ('Install') and resource ('skills from a GitHub repo'), and also explains the mechanism (clones repo, discovers SKILL.md, copies to local directory). This distinguishes it from sibling tools like skill_remove or skill_list_installed.
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 (installing skills from a GitHub repo) and gives source format examples. It does not explicitly mention exclusions or alternatives, but the context is unambiguous.
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?
Beyond the readOnlyHint annotation, the description explains that it returns a draft and that human review is required before committing, clarifying the tool's non-persistent behavior. It does not contradict the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 19 words, front-loaded with the primary action ('Scan'), and every phrase contributes meaningful information with no filler.
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?
For a read-only draft generator with two parameters and a simple response, the description covers the core behavior, return value, and key constraint (no writing to vault). The absence of an output schema is mitigated by the clear statement that it returns a draft.
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% for both parameters, so the schema already documents slug and project_path adequately. The description adds no additional parameter semantics, making a baseline score of 3 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 scans a git repo and generates a draft context.md, with a specific verb and resource. It distinguishes itself from write tools by explicitly noting it does NOT write to the vault.
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 drafting context that requires human review and explicitly notes it does not write to the vault, but it does not name specific alternatives or provide explicit when-to-use/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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes the tool is read-only. The description adds that it lists skills installed locally from GitHub repos, providing scoping but no additional behavioral details such as return format or network behavior. This is adequate but not rich.
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 states the action and resource without wasted words. It is perfectly concise for the tool's simplicity.
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?
For a simple list tool with no parameters, no output schema, and a read-only annotation, the description provides enough context to understand its purpose. There is no missing critical information.
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?
There are no parameters, and schema coverage is 100% by default. The description doesn't need to explain parameters. This baseline of 4 is appropriate for a zero-parameter tool.
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 action (list) and resource (skills installed locally from GitHub repos). It distinguishes from sibling tools like skill_install and skill_remove, which perform different 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 context is clear: use this tool when you want to see which skills are installed locally from GitHub repos. There are no explicit exclusions or alternatives mentioned, but given the simplicity of the list operation, the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description aligns with this by using 'Show'. It adds context about what aspects of the state are visible (loaded skills, weights, recent sessions), which is valuable beyond the annotation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It front-loads the main purpose and immediately lists the key components, earning the maximum score for efficiency.
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 zero-parameter read-only status tool, the description is sufficiently complete. It names the core content areas (loaded skills, weights, recent sessions). While it doesn't specify output format or provide deeper details, the simplicity of the tool makes this acceptable. Sibling tools like 'stats' exist, but the description distinguishes the knowledge graph focus.
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?
There are 0 parameters, so the baseline is 4. The description doesn't need to explain parameters but effectively communicates the scope of the operation by listing what will be shown.
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 shows superskill knowledge graph state with specific components (loaded skills, weights, recent sessions). It uses a specific verb 'Show' and a resource, differentiating it from sibling tools like 'stats' or 'skill_list_installed' which likely focus on different aspects.
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 clearly implies when to use this tool: when an agent needs to inspect the current state of the superskill knowledge graph. It does not explicitly mention alternatives or exclusions, but the context is clear enough for basic selection.
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:

[![superskill MCP server](https://glama.ai/mcp/servers/permanu/superskill/badges/card.svg)](https://glama.ai/mcp/servers/permanu/superskill)

Score Badge

Copy to your README.md:

[![superskill MCP server](https://glama.ai/mcp/servers/permanu/superskill/badges/score.svg)](https://glama.ai/mcp/servers/permanu/superskill)

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/permanu/superskill'

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