Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
OuterSpace Apizr exposes 7 tools via FastAPI HTTP endpoints. All tools have descriptions, but most descriptions are vague and do not meet the standard of 'prompt-engineered' clarity required for agent tool selection. Input schemas are partially visible: `process_file` and `analyze_file` accept `UploadFile` objects with minimal constraint documentation; `generate_gunicorn_files`, `generate_dockerfile`, `get_fastapi_code` accept complex configuration objects (DockerizrConfiguration, FastApizrConfiguration, Analyzr) whose schemas are NOT visible in the provided source and are inferred from type hints alone. Parameters lack type-level granularity and constraint descriptions (e.g., 'functions_to_analyze' is a comma-separated string with no validation rules or format specification). Error handling is minimal, the code shows generic HTTPException(400) catches without recovery guidance. No tool annotations (readOnlyHint/destructiveHint/idempotentHint) are present. Overall definition quality is fair at best; most tools fall into the 30-40 range individually.
Tools (7)
analyze_fileread onlysource verified48/100
Analyze a Python file for functions and metadata
convert_notebookwritesource verified57/100
Convert a Jupyter notebook to a Python script
generate_dockerfilewritesource verified41/100
Generate a Dockerfile for the project
generate_gunicorn_fileswritesource verified40/100
Generate Gunicorn WSGI and configuration files
get_fastapi_codewrite39/100
Generate FastAPI code from analysis metadata
healthread onlysource verified78/100
Health check endpoint
process_filewritesource verified48/100
Return a ZIP project; server-side output paths are intentionally not accepted.
Parameter constraints are underdocumented. 'functions_to_analyze' and 'ignore' are comma-separated strings with no format specification, min/max length, or validation rules. Agents cannot reliably format these inputs.
Descriptions lack LLM-optimized WHEN/WHY context. Most descriptions (process_file, analyze_file, generate_dockerfile, get_fastapi_code) explain WHAT but not WHEN to call or how the output feeds downstream tools. This forces agents to guess at composition order.
Make input type schemas visible and machine-readable in the MCP tool definition. For each complex type (DockerizrConfiguration, FastApizrConfiguration, Analyzr), define a JSON Schema with all required and optional fields, constraints, and examples. Register these in the FastAPI OpenAPI spec or export them explicitly.
Enrich descriptions with WHEN/WHY context. Example: 'analyze_file' should read: 'Analyze a Python file to extract function signatures and metadata. Call this after uploading a file with process_file to generate API stubs. Returns an Analyzr object passed to get_fastapi_code.' (120 chars, clear ordering).
Add format constraints to string parameters. For 'functions_to_analyze', specify: 'Comma-separated list of function names (e.g., "func_a, func_b"). If empty or omitted, analyzes all functions. Max 10 functions per call.' For 'ignore', similar: 'Comma-separated list of function names to skip during analysis (e.g., "_internal, __dunder").'
Add tool annotations. Mark write tools (process_file, generate_gunicorn_files, generate_dockerfile, get_fastapi_code, convert_notebook) with destructiveHint: true. Mark read tools (health, analyze_file) with readOnlyHint: true. Evaluate idempotency and set idempotentHint where applicable (process_file is likely idempotent if the temp dir is unique; convert_notebook depends on notebook source stability).
No output schemas documented. Tools return complex objects (ZIP archive, analysis metadata, generated code, Dockerfile) but responses are not formally specified. Agents cannot plan downstream calls without knowing what fields are returned.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Multiple tools write files (process_file, generate_gunicorn_files, generate_dockerfile, get_fastapi_code, convert_notebook) but are not marked with destructiveHint. Agents cannot distinguish safe reads from irreversible writes.
Error handling is minimal. Generic HTTPException(400) for multiple failure modes (ValueError, SyntaxError, UnicodeError, AnnotationException) gives agents no recovery guidance. Error responses should classify as retryable/user-fixable/fatal and suggest next steps.
No idempotency guarantees. If process_file or convert_notebook fails partway through (e.g., ZIP creation succeeds but cleanup fails), retry behavior is undefined. Agents may generate duplicate outputs.
process_fileconvert_notebook
Improve error handling. Replace generic HTTPException(400) with specific errors: 'ValueError: Invalid Python syntax in line 42. Fix syntax errors and retry.' 'UnicodeError: File encoding not UTF-8. Ensure file is UTF-8 encoded.' 'AnnotationException: Function 'main' missing return type annotation. Add type hints and retry.' For 'file_type not supported', return: 'File type .txt not supported. Supported: .py, .ipynb. Try uploading a Python or Jupyter file.' Each error should guide the agent toward recovery.
Clarify parameter types and defaults. Rename 'file' to 'python_file' (process_file) or 'notebook_file' (convert_notebook). Rename 'conf' to 'dockerizr_config' or similar. Document defaults: if 'functions_to_analyze' is omitted, all functions are analyzed; if 'ignore' is omitted, no functions are skipped.
Document tool composition order. Add a narrative in the server description or via a README: 'Typical workflow: (1) Call process_file or analyze_file to extract code structure. (2) Call generate_dockerfile, generate_gunicorn_files to create deployment assets. (3) Call get_fastapi_code to generate API stubs.' This guides agent planning.
Add pagination/streaming guidance if any tool returns large outputs (e.g., if analyze_file returns 1000+ functions). Cap results (e.g., max 100 functions per call) and document pagination in the response schema.
Consider adding a 'describe_configuration' tool that returns the schema and constraints for DockerizrConfiguration and FastApizrConfiguration, so agents can discover valid configuration options without hardcoding knowledge.