{"slug": "we-rewrote-all-50-of-our-mcp-tool-descriptions-to-get-into-claude-s-connectors", "title": "We rewrote all 50 of our MCP tool descriptions to get into Claude's Connectors Directory", "summary": "LastPing, a monitoring service for cron jobs, CI pipelines and AI agents, rewrote all 50 of its MCP tool descriptions to comply with Anthropic's Claude Connectors Directory policy, after an audit found 34 of the 50 contained instructions aimed at model behavior rather than the tool itself. The team converted those directives into factual statements, moved timing-sensitive guidance into tool results and skills, and cut one setup tool's default response from 65,283 to roughly 24,000 characters by returning client-specific installs only when the caller names its client. A CI test now checks every registered tool and parameter description to catch future drift.", "body_md": "I build [LastPing](https://lastping.dev), a monitoring service for cron jobs, CI pipelines and AI agents. It has a remote MCP server with 50 tools, so an agent can create monitors, read failed runs and write notes on incidents.\n\nThis week it was listed in Claude's Connectors Directory. Getting there meant rewriting every tool description we had. If you run an MCP server, the lesson applies to you whether or not you ever submit it anywhere.\n\nTool descriptions are the main thing a model sees about your tool, so over months of watching agents misuse ours, we kept adding instructions to them. When we audited before submitting, **34 of our 50 tools** contained text aimed at the model's behaviour rather than at the tool.\n\nSome real examples:\n\nCALL get_monitor FIRST and read its `routes` field\n\nPROPOSE, THEN ASK. Show the user what you found and get their agreement BEFORE calling this.\n\nSEND A NOTE WHETHER OR NOT YOU COULD FIX THE PROBLEM.\n\nIf you ARE Claude Code specifically, `hook_install` is available as an OPTIONAL SHORTCUT...\n\nEvery one of these was added for a good reason, usually after an agent did something wrong. Together they turned the tool list into a second system prompt that nobody had approved.\n\nAnthropic's directory policy boils down to this for tool descriptions:\n\nThe submission form even asks you to attest that your descriptions \"contain no instructions about model behavior, other tools, or external instruction sources\".\n\nReading that, our first worry was: if we delete the instructions, do agents get worse?\n\nIt turned out almost every instruction was hiding a **fact** that the model needed. The fix was to state the fact and let the model decide what to do with it.\n\n**Before:**\n\nTHIS REPLACES THE WHOLE SET for that event type — every destination you leave out stops receiving that event. CALL get_monitor FIRST and read its `routes` field.\n\n**After:**\n\nReplaces the whole destination set for that event type: destinations not listed stop receiving it, including ones someone else configured. get_monitor's `routes` field holds the current set, so adding a destination means sending the existing ids plus the new one.\n\nSame safety property. The model still learns that a partial list deletes routing, and where the current list lives. It's just no longer being ordered around.\n\nPROPOSE, THEN ASK. Show the user what you found and get their agreement BEFORE calling this — it CREATES monitors.\n\nCreates one monitor per source not already monitored; never deletes, pauses or edits existing monitors, so a scheduled re-run is safe drift detection.\n\nThe tool is also annotated as a write tool. Whether to confirm with the user first is up to the client and the user's permission settings, not the tool description. The description only has to be honest about what gets created.\n\n**Before (for an API key tool):** a paragraph about storing the key safely.\n\nCreates an API key. The plaintext key appears only in this result and cannot be retrieved again.\n\nA fact the model can act on, in one sentence.\n\nOur rules of thumb, which we wrote down and applied to every tool and every parameter:\n\nSome guidance genuinely matters. It moved to places where it applies at the right moment:\n\nThe difference: a description is read on every request whether the user asked for anything or not. A result or a skill is read when the user asked for it.\n\nOne tool, the one that returns setup instructions, produced **65,283 characters** per call. Most of it was installation details for coding agents the caller wasn't using.\n\nNow it returns the client-specific install only when the caller names its client (a `tool` parameter). The default response dropped to about **24,000 characters**, roughly a third. Nothing was removed; it's just not sent to clients that can't use it.\n\nDescriptions drift. Someone fixes a bug, adds \"IMPORTANT: always...\" and you're back where you started.\n\nSo we added a test that runs in CI over every registered tool and every parameter description. It fails on:\n\nWe checked the test by putting one of the old phrases back into a real tool and confirming CI went red. Plus a positive companion test, so an empty description list can't pass by accident.\n\nThis was the real fear. We ran the same tasks through Claude with the old descriptions and the new ones, using MCP tools only, and compared what it did: creating monitors from a description, wiring alerts, reading a failed run and writing a note back.\n\nBehaviour was the same. The tasks that worked before still worked, including the ones the old instructions were added to protect. In hindsight that makes sense: the model needed the facts, not the shouting.\n\nWe submitted, and the automated review approved LastPing as a Community connector the same day. It's now at [claude.ai/directory/lastping](https://claude.ai/directory/lastping).\n\nEven if you never submit to a directory:\n\n*I build LastPing. It watches cron jobs, CI pipelines and AI agents and tells you when they fail, stall or go quiet, and it's free for individuals. If you use Claude: Settings → Connectors → Discover → \"LastPing\". Other clients: [lastping.dev/mcp](https://lastping.dev/mcp/).*", "url": "https://wpnews.pro/news/we-rewrote-all-50-of-our-mcp-tool-descriptions-to-get-into-claude-s-connectors", "canonical_source": "https://dev.to/tp1111/we-rewrote-all-50-of-our-mcp-tool-descriptions-to-get-into-claudes-connectors-directory-11ji", "published_at": "2026-10-07 17:43:18+00:00", "updated_at": "2026-10-07 17:47:00.058926+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools", "mlops"], "entities": ["LastPing", "Anthropic", "Claude", "Claude Connectors Directory", "MCP"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/we-rewrote-all-50-of-our-mcp-tool-descriptions-to-get-into-claude-s-connectors", "markdown": "https://wpnews.pro/news/we-rewrote-all-50-of-our-mcp-tool-descriptions-to-get-into-claude-s-connectors.md", "text": "https://wpnews.pro/news/we-rewrote-all-50-of-our-mcp-tool-descriptions-to-get-into-claude-s-connectors.txt", "jsonld": "https://wpnews.pro/news/we-rewrote-all-50-of-our-mcp-tool-descriptions-to-get-into-claude-s-connectors.jsonld"}}