MCP Server Design — Make Agents Actually Call Your Tools
Why agents ignore working MCP tools, and how to fix it. Tool descriptions, result shapes, failure modes, and verification that does not assume.
Free
Works with the AI Agents you already use
Claude Code
Cursor
Codex CLI
Muse
Dots+22 moreClaude CodeCursorCodex CLIMuseDots
OpenClaw
Manus
Grok
Grok Bot+18 agentsMCP 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
| Component | Current | Recommended Improvement |
|---|---|---|
| Tool Name | search_logs | query_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 Shape | Raw string block | Structured 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
- Update the
descriptionin your tool definition to include the "When to use" context. - Modify the return function to wrap results in the structured JSON object shown above.
- 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.
How to use
Skills on Agensi run inside your AI agent. Copy the prompt, paste it into your agent, and it connects to Agensi and installs this skill for you. If a payment is needed, your agent shows it to you first.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill passes our trust checks below.
Security scanned
Passed our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free forever
No account required to browse
Trust & safety
Security scanned
Verified clean 1 day ago
- Free to download with an account
Requires
Git