MCP server providing stateful counter tools for AI assistants
Counter server has 9 tools with consistent naming (verb_noun pattern: counter_*) and reasonable descriptions (avg ~120 chars). All tools have input schemas with type definitions and parameter descriptions. However, output schemas are not documented in the source, responses are inferred from code logic. Error handling is minimal; no recovery guidance or actionable error messages. Tool descriptions lack WHEN-to-use context and dependency hints. No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels. Composition is sound (each tool does one thing), but descriptions could be more LLM-optimized per pattern:tool-description baseline (target 50-200 chars).
Decrement a counter by a specified amount (default: 1). Creates the counter if it doesn't exist. Use this to track consumed items, remaining tasks, or any countdown.
Delete a counter completely. Returns true if the counter was deleted, false if it didn't exist.
Get the current value and history of a counter. Returns null if the counter doesn't exist.
Get the operation history of a counter. Optionally limit the number of recent entries returned.
Increment a counter by a specified amount (default: 1). Creates the counter if it doesn't exist. Use this to track iterations, processed items, or any counting task.
List all counters with their current values and creation timestamps.
Parse and apply counter operations from specially formatted tags in text. Supports multiple tag formats for flexibility. Returns the final state of all affected counters and any errors encountered.
Output schemas not documented. Code shows Counter objects with id, value, history, created fields, but tool descriptions do not specify return structure. LLMs cannot plan downstream calls without knowing what fields to expect.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels. counter_delete is DESTRUCTIVE, counter_increment/decrement/set/reset are WRITE, counter_get/list/get_history are READ_ONLY. Annotations enable agents to reason about safety and retry logic.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 60 | 2026-07-28+ | v2 |
Reset a counter to 0. Returns null if the counter doesn't exist.
Set a counter to a specific value. Creates the counter if it doesn't exist.
Error handling lacks recovery guidance. Code catches errors but returns generic messages ('Failed to parse tag'). No actionable next steps for LLM. Per pattern:recovery-guide, errors should tell the agent what to do next.
counter_list lacks pagination. No limit parameter, no offset/cursor, no total count. If many counters exist, response could exhaust context window. Per pattern:paginated-result, list tools must support pagination.
Descriptions lack WHEN-to-use context and dependency hints. E.g., counter_get says 'Get the current value and history' but does not explain when to call it vs counter_get_history, or that it returns null if counter doesn't exist. Per pattern:tool-description, descriptions should guide selection.