Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
Companian MCP server has 4 tools with moderate structural issues. Tool schemas are partially visible but incomplete, descriptions exist but lack actionable detail, and parameter documentation is sparse. The fileOperations tool is dangerously broad (combining read, write, append, delete, execute into one verb-noun name that signals multiple responsibilities). Naming conventions are inconsistent: 'playYouTubeVideo' uses camelCase instead of snake_case verb_noun pattern, and 'fileOperations' + 'createWordDocument' + 'simpleDocCreator' lack uniform structure. Parameter descriptions are generic ('Path to input text file') without constraints, formats, or dependency documentation. No output schema documentation is visible. Error handling strategy is absent from code review. Security implications of fileOperations (command execution, file deletion) are undiscussed in code.
Tools (4)
createWordDocumentwritesource verified65/100
Create Word documents with custom content and formatting
fileOperationsdestructivesource verified40/100
Perform file system operations (read, write, append, delete, execute commands)
playYouTubeVideoread onlysource verified52/100
Play a YouTube video by searching for the provided query
fileOperations tool combines 5 distinct operations (read, write, append, delete, execute) into one tool, violating single-responsibility principle. Tool name 'fileOperations' does not start with a specific verb and signals 'and' semantics.
No output schemas documented for any of the 4 tools. LLMs cannot plan downstream tool calls or extract required data without knowing return types and field names.
Parameter descriptions lack actionable constraints: no min/max length, no regex patterns, no enum alternatives documented. Example: 'query' parameter in playYouTubeVideo has no format guidance; 'content' in createWordDocument has complex union type with no structure examples.
URGENT: Split fileOperations into 5 separate tools: read_file, write_file, append_file, delete_file, execute_command. Each tool should have a single, verb-noun name (e.g., 'read_file' not 'fileOperations'). Add separate confirmation_delete_file tool with explicit user approval pattern.
Document output schema for all 4 tools. Specify return type (object, array, string), all field names, field types, and whether pagination is supported. Example: playYouTubeVideo should return {video_id: string, title: string, url: string, duration: number}.
Add actionable constraints to all parameters: specify min/max length (e.g., query 2-100 chars), enum alternatives where applicable (operation: enum[read|write|append|delete|execute]), and regex patterns for structured inputs (e.g., file paths). Place these directly in parameter descriptions as LLMs cannot parse JSON Schema pattern fields.
Rename camelCase tools to snake_case verb_noun: 'playYouTubeVideo' → 'play_youtube_video', 'createWordDocument' → 'create_word_document', 'simpleDocCreator' → 'create_document_from_text'. Ensures consistency with baseline naming convention used in 90% of A+ tools.
Add disambiguation context: include in createWordDocument description: 'Use this for documents with custom formatting (titles, authors, table of contents, page numbers). Use create_document_from_text if converting a plain text file.' Similarly for simpleDocCreator.
Add error handling guidance to all tool descriptions. Example for playYouTubeVideo: 'If search returns no results, ask the user for a different search term.' For fileOperations: 'If delete fails due to permissions, list available files in that directory.' Per pattern:recovery-guide.
Naming conventions inconsistent: camelCase (playYouTubeVideo, createWordDocument) vs snake_case expectation. Per baselines, 90% of A+ tools use verb_noun pattern with snake_case. No tool follows this consistently.
createWordDocument and simpleDocCreator have overlapping intent ('create Word documents') but no description distinguishes when to choose one over the other. LLM cannot disambiguate.
Tool descriptions lack context on error cases, prerequisites, and when NOT to use the tool. Baseline A+ tools explicitly state 'Call this first to...' or 'Requires X permission'. Current descriptions are purely functional.
fileOperations 'execute' operation poses command injection risk if agent passes unsanitized input. No evidence of input validation, sanitization, or permission checks in code review.
playYouTubeVideo description says 'automatically search and play the first relevant video' but provides no guarantee of relevance, no fallback handling if search fails, no documentation of what 'play' means (open URL? stream?). Output schema missing.
playYouTubeVideo
Implement input validation and sanitization for fileOperations, especially 'execute' operation. Reject commands containing pipe (|), semicolon (;), backtick (`), and other shell metacharacters. Return error: 'Command cannot contain: | ; ` && || < > $( )'. Log all command executions for audit trail per pattern:audit-trail.
Add timeout parameter to fileOperations 'execute' operation (default 30s, max 300s). Return timeout error if command exceeds limit: 'Command execution timed out after 30s. The command may still be running. Provide a kill signal or wait longer.'
For createWordDocument, clarify 'content' parameter: add to description '(for arrays: [{text: string}, ...]; for objects: {heading: string, body: string, ...})' and document the expected structure. Consider splitting into separate parameters (text_content vs structured_content) to reduce ambiguity.
Add precondition documentation: state any required permissions, file system assumptions, or external dependencies. Example: 'Requires write access to output directory' or 'Requires internet connection for YouTube search'.