Skip to main content
Glama
Shanksg

clawskills-mcp

by Shanksg
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
JavaScript
Local

ClawSkills

A library of integration skill documents for the most common SaaS platforms used in go-to-market and operations workflows. Each skill doc teaches an AI agent, automation builder, or LLM how to reliably use a platform's API with working code examples, rate limit rules, error playbooks, and platform-specific version details.

What's in here

playbooks/
├── INDEX.md                 ← Workflow-level guides spanning multiple tools
├── hubspot-asana-onboarding.md
├── salesforce-hubspot-lead-sync.md
├── slack-jira-incident.md
└── zendesk-jira-bug-escalation.md

skills/
├── INDEX.md                 ← Start here: all tools, top workflows, quick-ref tables
├── ROADMAP.md               ← Phased build plan and governance model
├── monday/skill.md          ← Monday.com (GraphQL API v2026-01)
├── salesforce/skill.md      ← Salesforce Sales Cloud (REST API v67.0)
├── jira/skill.md            ← Jira Cloud (REST API v3)
├── dynamics365/skill.md     ← Microsoft Dynamics 365 (Dataverse Web API v9.2)
├── hubspot/skill.md         ← HubSpot CRM (API v3, 190 req/10s)
├── servicenow/skill.md      ← ServiceNow (Australia release, Table API)
├── zendesk/skill.md         ← Zendesk Support (API v2)
├── asana/skill.md           ← Asana (REST API 1.0)
├── github/skill.md          ← GitHub (REST API + GraphQL v4, 2026-03-10)
├── figma/skill.md           ← Figma (REST API v1, Webhooks V2)
├── slack/skill.md           ← Slack (Web API, Block Kit, Events API)
├── stripe/skill.md          ← Stripe (Payments API v2026-02-25, Billing, Connect)
├── notion/skill.md          ← Notion (REST API v2025-09-03, Pages, Databases, Blocks)
└── linear/skill.md          ← Linear (GraphQL API, Issues, Cycles, Webhooks)

Each skill.md follows the same structure:

  • What this skill enables — outcome-focused bullets

  • Best-fit use cases — table of 8–15 real workflows with triggers and success criteria

  • Key concepts & data model — objects, fields, relationships, IDs

  • Authentication & permissions — auth flows with working curl examples, least-privilege scopes

  • Common workflows (recipes) — 6–12 step-by-step recipes with request/response examples

  • Query patterns & filtering — pagination, incremental sync, dedup

  • Reliability: rate limits, retries, idempotency — verified limits, backoff code in Python

  • Error handling & troubleshooting — "if you see X, do Y" playbook

  • Security & compliance — PII, audit trails, token guidance

  • Testing checklist — QA checklist you can run against a sandbox

  • Sources — official doc links

Each skill tracks its own platform version and Last validated date in the document header. The MCP package has a separate npm version because it versions the server/tooling layer, not the underlying SaaS APIs.

The playbooks/ layer captures cross-tool workflows end to end: trigger, system sequence, field mapping, idempotency, failure policy, and operational guardrails.

Related MCP server: Skills Manager MCP Server

Use with Claude via MCP (recommended)

ClawSkills ships as an MCP server that exposes all skill docs as tools directly inside Claude.

npx -y clawskills-mcp

Or install permanently:

npm install -g clawskills-mcp

Add to your Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "clawskills": {
      "command": "npx",
      "args": ["-y", "clawskills-mcp"]
    }
  }
}

Once connected, Claude can call three tools:

  • list_skills — see all available skill docs

  • get_skill — fetch a full skill or a specific section (auth, rate-limits, recipes, errors, etc.)

  • search_skills — full-text search across all skills

How to use these skills with AI tools

With Claude (claude.ai or Claude Code)

The most direct use: paste a skill doc (or a section of it) into your conversation as context, then ask Claude to write integration code, debug an error, or plan a workflow.

Option 1 — Reference a specific section

[paste the "Authentication & permissions" section from skills/salesforce/skill.md]

Using the above, write a Python function that exchanges a JWT for an access token
and caches it until 5 minutes before expiry.

Option 2 — Full skill as system context

If you're using the Claude API, load the skill doc as part of the system prompt:

import anthropic

with open("skills/jira/skill.md") as f:
    jira_skill = f.read()

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    system=f"""You are an integration engineer. Use the following Jira skill doc as your
reference for all API calls, auth patterns, and error handling:

{jira_skill}

Always follow the rate limit and retry patterns from the skill doc.""",
    messages=[{
        "role": "user",
        "content": "Write a function that creates a Jira bug from a PagerDuty alert payload."
    }]
)

Option 3 — Claude Code (this repo)

If you're already in Claude Code with this repo open, just reference the file:

Using skills/hubspot/skill.md, write a Python script that syncs new Salesforce
leads (created in the last hour) to HubSpot contacts, deduplicating by email.

With ChatGPT / GPT-4

Use the skill docs as file attachments or pasted context in the ChatGPT interface.

In the ChatGPT web UI:

  1. Open a new conversation.

  2. Click the paperclip (attach file) and upload the relevant skill.md.

  3. Ask your question — ChatGPT will use the skill doc as reference.

Via the OpenAI API:

from openai import OpenAI

with open("skills/zendesk/skill.md") as f:
    zendesk_skill = f.read()

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "system",
            "content": f"You are an integration engineer. Reference this Zendesk skill doc for all API patterns:\n\n{zendesk_skill}"
        },
        {
            "role": "user",
            "content": "Write a webhook handler that creates a Zendesk ticket from an incoming JSON alert."
        }
    ]
)

With Cursor / GitHub Copilot (editor context)

Both tools pick up files in your project as context.

Cursor:

  • Add the relevant skill.md to your Cursor context via @file mention:

    @skills/monday/skill.md  Write a function that creates a Monday.com item
from a webhook payload with these fields: name, status, due_date, assignee_email

  • Or add skills/ to your Cursor rules (.cursorrules) so the agent always has context available for integration-related tasks.

GitHub Copilot Chat:

#file:skills/servicenow/skill.md

Write a Python function that creates a ServiceNow incident from a CloudWatch alarm.
Include proper error handling and the work_notes vs comments distinction.

With LangChain / LlamaIndex (RAG pipeline)

Use the skill docs as a knowledge base for a retrieval-augmented generation system. Each skill doc is self-contained and works well as a RAG document.

LangChain example:

from langchain_community.document_loaders import DirectoryLoader, TextLoader
from langchain.text_splitter import MarkdownHeaderTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma
from langchain.chains import RetrievalQA
from langchain_openai import ChatOpenAI

# Load all skill docs
loader = DirectoryLoader("skills/", glob="**/*.md", loader_cls=TextLoader)
docs = loader.load()

# Split by Markdown headers to keep sections coherent
splitter = MarkdownHeaderTextSplitter(
    headers_to_split_on=[("##", "section"), ("###", "subsection")]
)
chunks = []
for doc in docs:
    chunks.extend(splitter.split_text(doc.page_content))

# Index into vector store
vectorstore = Chroma.from_documents(
    chunks,
    embedding=OpenAIEmbeddings(),
    persist_directory="./skills_index"
)

# Query
qa = RetrievalQA.from_chain_type(
    llm=ChatOpenAI(model="gpt-4o"),
    retriever=vectorstore.as_retriever(search_kwargs={"k": 4})
)

answer = qa.invoke("What is the rate limit for HubSpot Pro and how do I handle 429s?")

LlamaIndex example:

from llama_index.core import SimpleDirectoryReader, VectorStoreIndex

documents = SimpleDirectoryReader("skills/", recursive=True).load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

response = query_engine.query(
    "How do I upsert a Salesforce contact by email and log a Task against it in one operation?"
)
print(response)

Injecting skill docs into Claude API calls

If you're building a custom agent using the Claude API with tool use, you can inject relevant skill docs based on which tool the agent is about to call:

import anthropic
from pathlib import Path

SKILL_DIR = Path("skills")

def get_skill(tool_name: str) -> str:
    """Load skill doc for a given tool slug."""
    skill_path = SKILL_DIR / tool_name / "skill.md"
    if skill_path.exists():
        return skill_path.read_text()
    return ""

def run_integration_agent(task: str, tools_needed: list[str]) -> str:
    """Run an agent that has skill docs injected for the tools it needs."""
    skill_context = "\n\n---\n\n".join(
        f"# {tool.upper()} SKILL REFERENCE\n{get_skill(tool)}"
        for tool in tools_needed
        if get_skill(tool)
    )

    client = anthropic.Anthropic()
    response = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=8192,
        system=f"""You are an integration engineer building reliable API integrations.

Use the following skill references for all API calls, auth flows, rate limiting,
and error handling. Do not deviate from the patterns described.

{skill_context}""",
        messages=[{"role": "user", "content": task}]
    )
    return response.content[0].text

# Example
result = run_integration_agent(
    task="Write a Python script that syncs Zendesk tickets (status=open, priority=urgent) to Jira bugs.",
    tools_needed=["zendesk", "jira"]
)

In a .claude/CLAUDE.md project instruction file

If you work in Claude Code regularly, you can tell Claude to always use these docs:

# Integration Skills

When writing code that integrates with any of the following tools, always read the
corresponding skill doc before writing code:

- Monday.com → @skills/monday/skill.md
- Salesforce → @skills/salesforce/skill.md
- Jira → @skills/jira/skill.md
- Dynamics 365 → @skills/dynamics365/skill.md
- HubSpot → @skills/hubspot/skill.md
- ServiceNow → @skills/servicenow/skill.md
- Zendesk → @skills/zendesk/skill.md
- Asana → @skills/asana/skill.md
- GitHub → @skills/github/skill.md
- Figma → @skills/figma/skill.md
- Slack → @skills/slack/skill.md
- Stripe → @skills/stripe/skill.md
- Notion → @skills/notion/skill.md
- Linear → @skills/linear/skill.md

Follow the auth patterns, rate limit handling, and error codes exactly as documented.
Always pin API version headers where specified.

Best practices for prompting with skill docs

Goal

What to include in the prompt

Write integration code

Full skill doc or the "Auth" + "Recipes" sections

Debug an error

"Error handling" section + the exact error message you received

Plan a workflow

"Best-fit use cases" table + "Key concepts" section

Review existing code

Full skill doc (the AI can spot deviations from documented patterns)

Handle rate limits

"Reliability" section only — it's self-contained

Set up webhooks

The webhook recipe from "Common workflows" + "Testing checklist"

Tips:

  • When working across two tools (e.g., Zendesk → Jira sync), include both skill docs.

  • For code generation, always mention the target language — the recipes are in curl/Python pseudocode by default.

  • The "Testing checklist" section at the bottom of each skill is useful as a prompt to verify generated code: "Check this code against the testing checklist in the skill doc."

Keeping skills current

Skills are validated against live API docs. Each doc has a Last validated: date in the header. Key things to watch:

  • Monday.com — new API version released every quarter; always pin API-Version header to 2026-07 (current) or check developer.monday.com/api-reference/docs/api-versioning

  • Salesforce — new API version each seasonal release (Spring/Summer/Winter); currently v67.0 (Summer '26). Check /services/data/ on your org for available versions.

  • Jira — GET /rest/api/3/search is deprecated; use POST /rest/api/3/search/jql

  • HubSpot — date-based versioning (/YYYY-MM/ paths) GA since March 2026 alongside v3; rate limits updated Sep 2024

  • ServiceNow — currently Australia release (March 2026); update URL bundle names on instance upgrade

  • GitHub — always pin X-GitHub-Api-Version: 2026-03-10 (26 breaking changes vs 2022-11-28); prefer fine-grained PATs over classic PATs; GITHUB_TOKEN in Actions is limited to 1,000 req/repo/hr

  • Figma — files:read scope is deprecated; use granular scopes (file_content:read, file_comments:write, etc.); rate limits updated Nov 2025 and now vary by plan + seat type

See ROADMAP.md for the full governance and update process.

Contributing

To add or update a skill:

  1. Create a branch: git checkout -b skill/<toolname>

  2. Follow the template structure in any existing skill.md — all 11 sections required.

  3. Verify all endpoints, rate limits, and auth flows against the official vendor docs before committing.

  4. Add a Last validated: date to the doc header.

  5. Update skills/INDEX.md and README.md when adding a new tool.

  6. Link to official sources in the ## Sources section — no unverified claims.

  7. Open a PR — CI runs npm test which validates that your skill loads and has all required sections.

Releases are automated in two stages, because main is protected and cannot be pushed to directly:

  1. GitHub Actions → Prepare Release → Run workflow → pick patch / minor / major. This opens a release/vX.Y.Z PR containing the version bump. Nothing is published yet.

  2. Merge that PR. Release then publishes to npm via OIDC and tags vX.Y.Z.

.github/workflows/release.yml must keep that filename — npm's trusted publisher config pins the workflow filename.

Available Tools

7 tools
get_playbookA

Retrieve a ClawSkills workflow playbook by name (slug).

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesPlaybook slug, e.g. 'zendesk-jira-bug-escalation'

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only uses the verb 'Retrieve' without disclosing behavior for nonexistent slugs, return format, authorization needs, or whether it errors or returns null. This is a significant gap for a tool with no annotation safety profile.

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, focused sentence with no filler words. Every word contributes to conveying the tool's purpose and key constraint (slug-based retrieval).

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?

As a simple one-parameter getter with no output schema, the description adequately identifies the resource type and lookup key. It does not specify return structure or error handling, but given the minimal complexity and clear verb, it is sufficiently complete for basic 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 input schema fully documents the 'name' parameter with a type, description, and example (100% coverage). The description's phrase 'by name (slug)' reiterates the schema without adding semantic value, 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 uses a specific verb ('Retrieve') and clearly identifies the resource ('ClawSkills workflow playbook') and lookup method ('by name (slug)'). It distinguishes itself from siblings like list_playbooks and search_playbooks by focusing on retrieving a single specific playbook.

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 you have the exact slug, but does not explicitly state when to use alternatives (e.g., search_playbooks if slug is unknown) or provide exclusions. There is no guidance on prerequisites or filtering.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_skillA

Retrieve a ClawSkills skill doc by name (slug). Optionally specify a section (e.g. 'auth', 'rate-limits', 'recipes') to get just that part.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesSkill slug, e.g. 'salesforce', 'github', 'figma'
sectionNoOptional section name. Aliases: auth, rate-limits, errors, pagination, recipes, gotchas, webhooks, overview, fields

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the transparency burden. It clearly conveys the read-only nature via 'Retrieve' and discloses the optional section-filtering behavior. It doesn't cover error cases or return format, but for a simple read operation this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the primary action and resource. The example section list adds immediate clarity without unnecessary verbosity.

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), and the description adequately covers what it does, including the optional section behavior. A mention of return format could enhance completeness, but it's not critical given the description's clarity.

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%—both parameters have descriptions, and 'section' lists aliases. The description adds context by exemplifying section values ('auth', 'rate-limits') and explaining that the section returns 'just that part', which slightly enhances the schema but doesn't carry the burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a specific action ('Retrieve') and resource ('ClawSkills skill doc') with a clear lookup method ('by name (slug)'). This distinguishes it from siblings like list_skills and search_skills, which are for discovery, and from get_playbook, which targets a different resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'by name (slug)' implies the tool should be used when the caller already knows the skill's slug. However, it doesn't explicitly mention alternatives like 'use search_skills if you don't know the slug' or list_skills for browsing, leaving the usage guidance implicit rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_playbooksA

List all available ClawSkills workflow playbooks.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden for behavioral disclosure. It only restates the function (list all) and provides no details about return format, ordering, potential side effects, or response size, leaving the agent without helpful 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 a single, focused sentence. It is concise and front-loaded, with no redundant or filler words, earning a perfect score for conciseness.

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 (zero params, no output schema), the description adequately explains its purpose. However, it could be more complete by specifying what the returned list contains (e.g., names, metadata, or IDs), but this is a minor gap for a straightforward list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool accepts no parameters, so the schema already captures everything needed. The description adds no parameter-specific semantics, but none are required, aligning with the baseline of 4 for zero-parameter tools.

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 action (list) and specific resource (all available ClawSkills workflow playbooks). It distinguishes from siblings like get_playbook and search_playbooks by indicating it returns everything rather than a specific item or filtered set.

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 when you want all playbooks) but does not explicitly contrast with alternatives or state when not to use it. For example, it does not mention search_playbooks for filtered queries, so guidance is only implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_skillsA

List all available ClawSkills API integration skill docs.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It indicates a read-only 'list' operation and the scope ('all available'), but does not disclose return format, pagination, or potential size limits. For a simple list tool, 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, clear sentence that is front-loaded with the action verb. Every word earns its place, and there is no fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool, the description is sufficiently complete. It defines what is listed and the scope. While no output schema exists, the phrase 'skill docs' gives a reasonable idea of what will be returned. It could potentially mention sorting or filtering, but that is not needed for a simple list-all operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, and the schema confirms this with an empty properties object. The description does not need to explain parameters, and the baseline of 4 applies. No additional semantic information is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and the resource ('all available ClawSkills API integration skill docs'). It distinguishes from sibling tools like get_skill (fetch a single skill) and search_skills (search for skills), as 'list all' implies a comprehensive directory.

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 'all available' implies when to use it (to enumerate all skills docs) and implicitly contrasts with search_skills, but no explicit alternatives or exclusions are mentioned. The usage context is clear, but the description does not explicitly say when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_clawskillsA

Search across both skills and playbooks. For workflow-shaped queries, playbooks are ranked ahead of generic skill matches.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query, e.g. 'closed won onboarding', 'zendesk jira escalation', 'lead sync'

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses a meaningful behavioral trait: playbooks are ranked ahead of generic skill matches for workflow-shaped queries. However, it omits other behavioral details such as result format, pagination, or any permission requirements, leaving room for improvement.

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 exceptionally concise—two sentences that front-load the core purpose and then add a useful ranking nuance. Every word earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter search tool with no output schema, the description covers the essential purpose and a behavioral nuance. It could be more explicit about when to prefer sibling tools, but the overall context is sufficient for correct usage.

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 for the single 'query' parameter, including example values. The description adds no further parameter-level detail beyond what the schema already offers, so a baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Search across both skills and playbooks.' This is a specific verb-resource pairing that immediately distinguishes it from sibling tools like search_skills and search_playbooks, which focus on one resource type.

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 usage context by indicating that this tool is for searching across both resources, and adds a ranking behavior for workflow-shaped queries. However, it does not explicitly name alternatives or state when to use separate search tools, so it falls short of a complete 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_playbooksA

Search across workflow playbooks for a query string and return matching excerpts with context.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query, e.g. 'idempotency', 'rollback', 'customer impact'

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears the full burden. It states the tool returns 'matching excerpts with context,' which implies a read-only behavior, but it does not explicitly disclose side effects, permissions, or absence of mutation. The transparency is adequate for a search tool but not fully explicit.

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 directly communicates purpose and return value without any wasted words or redundant 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?

Given the tool's simplicity (one parameter, no output schema), the description covers the core purpose and expected return. However, it lacks context about how this search differs from sibling search tools like search_skills, leaving a minor completeness gap.

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 of the single 'query' parameter, including examples. The description adds no additional meaning beyond the schema, 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 tool's action ('Search'), resource ('workflow playbooks'), and return value ('matching excerpts with context'). This distinguishes it from sibling tools like list_playbooks and get_playbook, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage — searching across playbooks — but does not provide explicit when-to-use guidance or contrast with sibling search tools like search_skills. Users are left to infer when to choose this over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_skillsA

Search across all skill docs for a query string. Returns matching excerpts with context. Useful when you don't know which skill to fetch.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query, e.g. '429 retry', 'OAuth scopes', 'webhook signature'

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the tool returns excerpts with context, indicating read-only search behavior. It does not detail pagination or matching semantics, but for a search tool this is reasonably transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, and includes a usage tip. Every word earns its place with no fluff.

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 one-param tool with no output schema, the description covers purpose, output type, and use case sufficiently. It lacks edge-case mentions but is complete enough for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a descriptive example-laden parameter. The description adds no new parameter semantics beyond saying 'for a query string,' which is also in the schema. Baseline 3 applies as the schema already handles 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 clearly states the tool searches across all skill docs for a query string and returns matching excerpts with context. It distinguishes from siblings like list_skills and get_skill by specifying the search/fetch behavior for when the target skill is unknown.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Useful when you don't know which skill to fetch,' providing a clear use case that differentiates it from get_skill and other siblings. The context signals also list sibling tools, making the alternative contexts implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.0.0
    • First observedget_playbook
    • First observedget_skill
    • First observedlist_playbooks
    • First observedlist_skills
    • First observedsearch_clawskills
    • First observedsearch_playbooks
    • First observedsearch_skills
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: list/get/search for skills, list/get/search for playbooks, plus a combined cross-search. No two tools appear to do the same thing, and the combined search is explicitly differentiated.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern: list_* for listing, get_* for fetching a single item, search_* for querying. The singular/plural usage is appropriate, and the combined search_clawskills fits the pattern.

Tool Count5/5

With 7 tools, the server is well-scoped for a documentation lookup service. Each tool maps to a clear operation on one of two resource types, and there is no bloat or unnecessary duplication.

Completeness5/5

For a read-only knowledge base of skills and playbooks, the surface fully covers the core operations: list all, get one (with optional section), and search. No obvious gaps exist for the stated purpose.

Maintenance

ActivitySlowing
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers