This MCP server has severe definition quality issues. The tool 'execute_skill_action' exists but lacks critical production-grade documentation. The input schema is minimal (only two string parameters with basic descriptions), output schema is completely undocumented, and the tool description is vague about actual behavior and side effects. The codebase does not show proper tool registration via the MCP protocol, only a JSON print statement. Most critically, there is no evidence of the tool actually being implemented, only a trivial client stub. The server appears to be a skeleton/prototype rather than a functional MCP implementation.
Tools (1)
execute_skill_actionwritesource verified33/100
Execute a skill action and transition the agent state machine to the next state
No visible tool registration or MCP protocol implementation. The mcp_server.py only prints a JSON status message; there is no evidence of actual MCP server framework, request/response handling, or tool method binding.
Output schema completely undocumented. The tool description does not state what fields are returned, their types, or what 'next state' represents. LLMs cannot plan downstream calls without knowing the response structure.
Tool description is vague and lacks critical information. 'Execute a skill action and transition the agent state machine to the next state' does not explain: what skill actions are valid, what states exist, what happens on error, whether this call is idempotent, or what prerequisites exist.
Implement a proper MCP server using the official Python SDK (mcp or similar). The current code does not handle MCP protocol messages (initialize, call_tool, etc.). Replace the stub with a real server that registers tools with full schemas.
Add a complete input schema for execute_skill_action: define 'action' as an enum of valid actions (e.g., 'start', 'process', 'finish', 'pause', 'cancel') and 'current_state' as an enum of valid states (e.g., 'idle', 'running', 'paused', 'completed'). Use JSON Schema with type and enum constraints.
Document the output schema explicitly. Specify that the response is an object with fields: { 'next_state': string, 'status': 'success'|'error', 'message': string?, 'reason': string? }. Include type and description for each field.
Rewrite the tool description to explain WHEN to use this tool and WHAT it does in detail: 'Transitions the agent state machine from current_state by executing the specified action. Returns the next state and whether the transition succeeded. Use this to advance the agent's workflow step-by-step. Actions like start, process, and finish correspond to different stages of a skill execution lifecycle.'
Add per-parameter descriptions with explicit constraints: 'current_state (required, string): The agent's current state. Must be one of: idle, running, paused, completed. State represents where in the workflow the agent currently is.' and 'action (required, string): The action to execute. Must be one of: start, process, finish, pause, cancel. The action triggers the state transition.'
Score history
Overall score trend
First recorded score · v2 rubric
26/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-23
F
26
2026-07-28+
v2
Parameter descriptions are generic and lack constraints. 'The action to execute' and 'The current state of the agent' do not state: what actions are valid, what states are valid, format requirements, or length limits. LLMs will hallucinate values.
Tool name 'execute_skill_action' lacks clarity on what 'skill action' means in context. Does it invoke a workflow, update state, or trigger an external service? The name does not convey intent clearly enough for LLM disambiguation.
No error handling guidance. The tool description does not state what errors are possible, whether they are retryable, or what the agent should do next. A call returning an error provides no recovery path.
No idempotency contract. The description does not state whether repeated calls with the same inputs produce the same result. If 'execute_skill_action' transitions state, is it idempotent? Agents rely on this to safely retry.
execute_skill_action
Add error handling guidance to the tool description: 'On error, returns status: error with a message (e.g., "Invalid action: pause is not allowed from state idle"). Retryable errors are rare; check the action and current_state match valid transitions before retrying.'
Declare the idempotency contract: 'This tool is idempotent when action is idempotent (e.g., start is idempotent if called twice from idle). Non-idempotent actions (e.g., finish may not be repeatable) will error on retry. Check tool output to confirm state transition succeeded.'
Add tool annotations: Mark the tool with a destructiveHint if state transitions are irreversible, or with an idempotentHint if safe to retry without side effects.
Implement the actual backend logic in client.py (or a new service module). The current AgentStateMachineTrackerClient.transit() is a stub that always returns 'completed' or 'processing'. Build a real state machine with validation, error handling, and audit logging.
Add per-request error reporting: When a transition fails, return a structured error object with a code, message, and recovery hint (e.g., 'code: invalid_transition, message: cannot finish from running state, hint: call execute_skill_action with action=pause first').