MCP Server Design — Make Agents Actually Call Your Tools

    1

    Why agents ignore working MCP tools, and how to fix it. Tool descriptions, result shapes, failure modes, and verification that does not assume.

    Free

    1 useSecurity scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    MCP Server Design — Make Agents Actually Call Your Tools

    Example session with this skill installed

    My tool for searching logs is being ignored by Claude. Here is the current description: 'Search logs for errors.' How can I fix the description and result shape?

    • Read your context and instructions
    • Compiled the mcp server design

    I have audited your log search tool. The current description is too vague for the agent to understand the scope, and "nothing found" results are likely causing the agent to stop its search prematurely.

    MCP Tool Optimization

    ComponentCurrentRecommended Improvement
    Tool Namesearch_logsquery_application_logs
    Description"Search logs for errors.""Searches production application logs (JSON/Plaintext). Use when debugging 500 errors or investigating stack traces. Returns timestamp, severity, and message fields."
    Result ShapeRaw string blockStructured JSON list with timestamp, level, message, and trace_id.
    Empty State[]{"status": "no_results", "hint": "No errors found in the last 1h. Try widening the timeframe or checking debug logs."}
    // Recommended Result Schema
    {
      "results": [
        {
          "timestamp": "2023-10-27T10:00:01Z",
          "level": "ERROR",
          "message": "NullPointerException in UserService",
          "file": "src/services/user.ts",
          "line": 42
        }
      ],
      "truncated": false,
      "total_matches": 1
    }
    

    Next steps

    1. Update the description in your tool definition to include the "When to use" context.
    2. Modify the return function to wrap results in the structured JSON object shown above.
    3. Restart your MCP server to clear the client's cached tool schema.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    An MCP server can be correct and still be dead. The failure is rarely in the function body — it is in the surface the agent reads before deciding whether to call it at all.

    A server that routed five languages described its tools as handling one. Four of the five were unreachable in practice, working perfectly, called by nobody. The fix was three docstrings.

    Every lesson here came from measuring a running server, not from reading the

    specification

    · The description is the product — the agent reads nothing else · Never return an empty list when the answer exists under a different filter · Normalise results across backends, or every consumer special-cases · Cap output and flag truncation — a silent cut is worse than a long list · Errors are results: name the command that fixes them · Ship setup inside the package, or the install never finishes

    Plus the verification pass most people skip: confirming the client sees the build you think it does, checking the agent picks the tool unprompted, and proving the install from an empty environment.

    Includes before/after rewrites of real tool descriptions, a reference on result shapes an agent can act on, and a pre-release verification checklist.

    Focuses on the interface and agent interaction surface. Does not provide business logic or API credentials. Requires a running MCP environment for verification.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    1 use

    Times used to date

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 29 days ago

    • Free with an Agensi account

    Requires

    Code Security Setup MCP
    Git

    Permissions

    Read Files
    Network Access
    Listed29 days ago

    What's inside

    Frequently Asked Questions

    This skill focuses on the "activation surface" of your server—optimizing tool descriptions and result schemas so LLMs actually recognize when and how to call your tools, rather than ignoring them or failing to parse the output.

    Yes, this skill is designed to work with any server built using the official TypeScript or Python SDKs and is optimized for use in clients like Claude Desktop and Cursor.

    It addresses 'false negatives' where an agent assumes data doesn't exist because of a strict filter; the skill provides patterns for 'result widening' to ensure the agent stays engaged even when initial queries return empty.

    You receive a comprehensive design framework, auditing templates for your tool schemas, and best-practice patterns for result normalization and failure handling.

    The skill focuses on the protocol interface and agent interaction layer; you will still need to provide your own business logic, API keys, and backend data sources.

    New in LLM Ops