Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
This server has 22 tools with significant definitional gaps. While tools are registered and have names following verb_noun convention (e.g., planfix_search_task, planfix_create_contact), the source code inspection reveals incomplete schemas and minimal descriptions. Most tool files are not shown in the provided code excerpt, making full assessment difficult, but based on the server.ts structure and available evidence: (1) Tools are imported and registered in TOOLS array, indicating they exist and are discoverable. (2) No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are visible in the server definition. (3) The CallToolRequestSchema handler wraps responses in a generic structure (getAnswerJson) with 'error' field support, but no evidence of structured output schemas or pagination support. (4) Error handling is minimal: catches exceptions and returns them as text, with no actionable recovery guidance, categorization, or field-level validation messages. (5) Parameter descriptions and constraints cannot be verified from the provided code snippet, tool definition files themselves are not shown. Without seeing the actual tool implementation files (src/tools/*.ts), I must score conservatively based on what IS visible: basic registration without inline schema evidence.
No tool descriptions visible in the provided code. Tool definitions reference files in src/tools/*.ts which are not shown. Cannot verify if descriptions exist in those files, but based on the server.ts registration and the CallToolRequestSchema handler structure, no descriptions are embedded in the registration path. LLMs cannot determine when or why to select a tool without descriptions.
Examine src/tools/*.ts files to extract and document tool descriptions (10-1024 characters each). Each description must state WHAT the tool does, WHEN to use it, and whether it modifies state. Example: 'Create a new task in Planfix. Call this after searching for an existing task to confirm it does not already exist. This operation creates a record that cannot be undone.'
Add input parameter type definitions and descriptions to all 22 tools. Every parameter needs: type (string|number|boolean|array|object), description (50-200 chars), and constraints (enum, pattern, min/max). Example: { name: 'priority', type: 'string', enum: ['low', 'medium', 'high', 'urgent'], description: 'Task priority level. Defaults to medium if omitted.' }
Implement tool annotations in the TOOLS array registration. Mark all WRITE tools (planfix_create_*, planfix_update_*, planfix_add_to_lead_task) with destructiveHint=true. Mark all READ_ONLY tools with readOnlyHint=true. This enables LLMs to distinguish side effects during planning. See mcp-sdk Tool type definition for annotation fields.
Enhance error handling in src/server.ts CallToolRequestSchema handler. Instead of returning raw error messages, categorize errors and provide actionable guidance. Example: if (!tool?.handler) return getAnswerJson({ error: 'Tool not found', recoveryHint: 'Try calling planfix_reports_list to discover available tools.' }). For validation failures, return the constraint violated and valid options.
Add pagination support to search and list tools. Update planfix_run_report, planfix_reports_list, and all search_* tools to accept 'limit' (default 20, max 100) and 'offset' (default 0) parameters. Return { results: [...], total: N, offset: O, limit: L } to signal available pagination. Cap results at 50 items by default.
Spec posture evidence
Inferred effective spec: 2025-06-18+.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Input schemas not visible for any tool in provided code excerpt. Tool files are referenced but not shown. Without viewing src/tools/*.ts files, cannot confirm if parameters have types, descriptions, enums, or constraints. Scoring conservatively assumes schemas are missing or minimal.
Error handling is generic and non-actionable. In src/server.ts, the CallToolRequestSchema handler catches all errors and returns { error: error.message } wrapped in getAnswerJson(). No error categorization (retryable vs user-fixable vs fatal), no recovery guidance, no field-level validation messages. LLMs cannot determine next steps from a raw error message.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are declared. The server has 9 READ_ONLY tools and 13 WRITE tools, but the tool registration in TOOLS array includes no annotations. This prevents LLM planning from understanding which tools have side effects. Critical for agents to know which operations are reversible.
Generic tool 'planfix_request' exposes raw API call interface without abstraction. Naming 'request' is too generic and violates verb_noun convention. This tool likely requires deep API knowledge and bypasses the user-friendly abstractions the other 21 tools provide. LLMs will struggle to know when to use it vs the specific tools.
No pagination parameters or result limiting documented. Search and list tools (planfix_search_task, planfix_reports_list, planfix_run_report, etc.) return results but no indication of pagination support, result limits, or offset/limit parameters. Large result sets risk context window overflow and degraded LLM reasoning.
Rename planfix_request to a more specific name or document its purpose clearly. If it's a raw API gateway, consider wrapping it with input validation and response shaping so LLMs do not accidentally pass malformed requests. If it's meant for advanced users, mark it with a special annotation or documentation that it requires API expertise.
Document output schemas for each tool. Create a schema reference (e.g., in a TOOLS_SCHEMA.md file or inline) listing expected response fields, types, and nullable status. Example: 'planfix_create_task returns { id: string, name: string, status: enum, created_at: ISO8601 }.' This helps LLMs plan downstream calls.
Add dry-run or confirmation support for destructive operations (planfix_create_*, planfix_update_*, planfix_add_to_lead_task). Introduce a 'confirm: boolean' parameter defaulting to false, requiring the agent to call with confirm=true after inspecting the operation details. This prevents accidental data loss.
Review parameter naming consistency across related tools. Ensure that if planfix_create_task accepts a 'project_id', then planfix_search_task returns 'project_id' (not 'project' or 'projectId'). Consistent naming allows LLMs to chain tools without field mapping confusion.
Add descriptions to all parameters in each tool. Avoid generic 'task ID', specify format and example: 'Planfix task ID (numeric, e.g. 12345). Obtain from planfix_search_task.' This guidance prevents LLMs from passing invalid values and guides multi-step planning.