Output schemas are not documented for any tools. LLMs cannot predict what fields to expect, forcing them to guess about downstream chainability. E.g., figma_get_file returns a Figma file object, but what fields does it contain? Does get_file_nodes response include node positions?
Error handling is absent or non-actionable. No error messages guide the LLM on recovery steps. E.g., 'Audio file not found: /path/to/file' does not suggest what to do next. No categorization of retryable vs user-fixable errors.
get_audio_length
Recommendations
Add explicit output schemas to every tool. Document the structure of returned objects: e.g., get_audio_text returns {transcribed_text: str, start_time: float, end_time: float, model_used: str}. This enables LLMs to plan downstream calls.
Implement confirmation-request pattern for destructive tools: execute_command should support a dry_run param; forget should require a confirm_session_id param or split into forget_session and forget_all; figma_delete_comment should require a confirmation token or offer a separate delete_comment_and_purge tool.
Enhance error handling with recovery guidance. Replace 'Audio file not found: /path' with 'Audio file not found at /path. Ensure the path is absolute and readable, or call list_audio_files() to find available files.' Categorize errors: if a Figma API call fails due to auth, suggest 'Check FIGMA_API_KEY environment variable'.
Expand parameter descriptions with format constraints and examples (avoid example values, use patterns instead). E.g., 'model_name: One of [tiny, base, small, medium, large]. Tiny is fastest (1s audio in ~0.5s) but least accurate; large is slowest but most accurate. Default: base (balanced).'
Add permission gates to execute_command. Require an explicit allow_execute_command=true parameter or validate against a whitelist of safe commands. Log all executions with timestamp, command, and result.
Document pagination and result limits. Add to search_with_tavily, search_with_duckduckgo, figma_get_team_projects: 'Returns up to <N> results per page. Use cursor param to fetch the next page. Total result count is provided in the response metadata.'
Parameter descriptions are minimal or missing context. E.g., 'think' tool has a param 'thought' with description 'A thought to think about', this is circular and unhelpful. 'model_name' for Whisper should clarify performance/speed tradeoffs (tiny=fastest but less accurate, large=slowest but most accurate).
High-risk operations (execute_command with timeout=30s default) lack permission gates or audit logging. An agent could execute shell commands without explicit user authorization or logged evidence. No security.pattern:permission-gate or audit trail.
Some parameter descriptions lack format/constraint guidance. 'url' parameters for save_html, get_html, convert_url_to_markdown do not specify valid URL schemes (http/https only?), character limits, or redirect behavior. This invites malformed input from LLMs.
Tools that return lists (search_with_tavily, search_with_duckduckgo, figma_get_team_projects, figma_get_project_files) support pagination but lack explicit documentation of result limits and cap guidance. No statement of 'returns up to 20 results' or 'use cursor for next page'.
Tool 'forget' has vague description 'Clear all memories in the memory database' and no confirmation step. Calling this deletes all user memories irreversibly, should require a session_id confirmation or offer forget_session vs forget_all.
execute_command tool description does not specify security sandbox or runtime constraints. Can agents execute 'rm -rf /' or call external network commands? No description of shell type (bash, sh, cmd.exe), available utilities, or forbidden patterns.
Parameter names and descriptions mismatch in some Figma tools. 'node_ids' (plural) in figma_get_file_nodes but 'ids' (plural, unqualified) in figma_get_image. 'svg_include_id' in figma_get_image but no mention of what format is returned or how to parse SVG.
figma_get_file_nodesfigma_get_image
Add tool annotations (readOnlyHint, destructiveHint) to make risk explicit to clients. Mark execute_command, forget, figma_delete_comment with destructiveHint=true so clients can warn users before execution.
Clarify sandbox and constraint rules for execute_command. Document: shell type (bash/sh assumed?), available utilities, resource limits (CPU, memory, disk), network access policy, and forbidden patterns (e.g., 'rm -rf /', 'sudo', etc.).
Standardize parameter naming across tool families. Use consistent suffixes: node_id vs node_ids (plural array), not ids. Use api_key patterns for optional credentials; document which tools need authentication.
Add input validation error messages that tell the LLM how to fix issues. E.g., if time_range in search_with_tavily is invalid, return 'time_range must be one of: day, week, month, year. Got: "fortnight". Did you mean: week?'
Provide batch variants or note single-item limits. If recall returns 5 memories but the user needs cross-session search across 50 sessions, clarify that recall is designed for single queries, not batch retrieval.
Document idempotency guarantees. Is calling create_file twice with the same name idempotent (overwrites) or an error? This guides agent retry logic.
Add rate limiting guidance. Specify max calls per minute for expensive operations (flux_generate_image, search_with_tavily) to prevent runaway agents from exhausting API quotas.