Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server has 6 tools with partial schema definitions and descriptions. Most tools have basic descriptions (50-100 chars range) and input schemas with parameter types, but descriptions are generic/minimal, missing context about when to use each tool and its side effects. Parameter descriptions lack detail on formats, constraints, and relationships. No output schemas are documented. Error handling is present but generic. Tool naming follows action-verb conventions (open_, close_, list_, apply_, validate_, force_close_), which is good, but several tools lack clarity on dependencies and usage patterns. The codebase shows error templates and session validation helpers, suggesting attention to error handling, but those details don't appear in the tool definitions themselves. Overall, this is a functional but basic implementation, most tools score in the 40-60 range individually.
Output schemas are not documented for any tool. Callers cannot know what fields to expect in responses, forcing the LLM to guess or parse unstructured text. This violates the 'documented return types' baseline (100% of A+ tools have them).
Parameter descriptions are minimal and lack constraints. E.g., 'filepath' has no guidance on absolute vs. relative paths, supported formats, or error cases. 'formula' has no language spec (Excel? Python? xlwings dialect?). Cell address format not documented. These ambiguities force the LLM to guess or fail.
State-change implications not documented. Tools like close_workbook and apply_formula are destructive (WRITE/WRITE risk), but descriptions don't state this or warn about side effects. LLMs need explicit 'this modifies state' declarations to reason about retry safety and ordering.
Recommendations
Add output schema documentation to every tool. For open_workbook, document that it returns {session_id: string, filepath: string, visible: boolean, read_only: boolean, sheets: string[]}. For list_workbooks, document the structure of each session object. Use a structured format (JSON Schema comment or docstring) so it's machine-parseable.
Expand parameter descriptions with explicit constraints. E.g., filepath: 'Absolute or relative path to an Excel file (.xlsx, .xls, or .xlsm). Relative paths are resolved from the server's working directory.' For formula: 'Excel formula syntax (e.g., =SUM(A1:A10), =IF(B1>0,"yes","no")). Invalid syntax will be rejected; use validate_formula_syntax first to check.',
Add state-change declarations to descriptions. E.g., close_workbook: 'Closes an open workbook session. If save=true, unsaved changes are persisted to disk (DESTRUCTIVE if data loss is possible). If save=false, changes are discarded.' apply_formula: 'Applies a formula to a cell, immediately modifying the workbook in memory. Changes persist if the workbook is later saved.'
Rename 'force_close_workbook_by_path_tool' to 'force_close_workbook' or 'discard_workbook'. Update description to clarify: 'Force-closes a workbook by file path without saving. Use this when a workbook is locked by another process. Data loss is possible if there are unsaved changes.'
Remove or retire the deprecated 'filepath' parameter from validate_formula_syntax. If session_id is the new standard, document the migration: 'Previously, filepath was supported. Use session_id instead, it's more efficient and tied to the open workbook session.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Tool naming issue: 'force_close_workbook_by_path_tool' is verbose and unclear. The '_tool' suffix is redundant. The 'force' + 'without saving' distinction from close_workbook is not obvious from the name alone. Consider 'force_close_workbook' or 'discard_workbook'.
validate_formula_syntax has both session_id (preferred) and filepath (deprecated, legacy) parameters. This creates ambiguity, which should the LLM use? Keeping deprecated params in active schemas is a maintenance hazard. Either retire filepath or clearly document the migration path.
No dependency documentation between tools. E.g., apply_formula and validate_formula_syntax both operate on sessions, but descriptions don't explain that you must call open_workbook first, or what happens if session_id is invalid. This forces the LLM to infer the workflow.
Error handling is present in the code (ERROR_TEMPLATES dict, exception classes) but not surfaced in tool descriptions. Descriptions don't say 'If session_id is invalid, you'll get a SESSION_NOT_FOUND error, call open_workbook() to create a new one.' This guidance is critical for LLM error recovery.
Add dependency hints to tool descriptions. E.g., open_workbook: 'Call this first to open a workbook and obtain a session_id. Pass session_id to apply_formula, validate_formula_syntax, and close_workbook.' apply_formula: 'Requires a valid session_id from open_workbook(). If session_id is invalid or expired (10 minutes of inactivity), you'll get SESSION_NOT_FOUND, call open_workbook() again.'
Document error scenarios and recovery paths. E.g., apply_formula: 'If the formula syntax is invalid, you'll get a validation error. Call validate_formula_syntax() first to test the formula before applying it. If the session expires, call open_workbook() to create a new one.'
Add pagination and result limits guidance if list_workbooks can return many sessions. E.g., 'Returns a list of all currently open workbook sessions. If many sessions are open, consider implementing pagination to avoid overwhelming the LLM's context.'
Document cell address format constraints. E.g., cell parameter: 'Cell address in Excel notation (e.g., A1, B2, AA10). Range references (e.g., A1:B10) are not supported; use apply_formula to a range with a formula like =SUM(range) instead.' This prevents invalid input.