Descriptions critically short and uninformative. All 9 tools have descriptions under 40 characters (e.g., 'Convert YouTube video to markdown'). Production baseline is 194 chars. Descriptions lack WHEN to call, dependencies, prerequisites, and return type hints. LLMs cannot reliably select tools without richer context.
Input schemas severely underspecified. Parameters like 'url', 'file_path', 'selector', 'items', 'type' lack type definitions, enums, range constraints, and format documentation. Example: 'items' in batch_convert is typed as 'array' with no inner type, no length limit, no examples of valid structure. 'selector' in browser_extract has no guidance on valid CSS selector syntax. 'type' in queue_submit lists allowed values in description but not as formal enum constraint.
Expand all 9 tool descriptions to 100-200 characters. Include: (1) what the tool does, (2) when to call it, (3) what it returns, (4) any prerequisites. Example for convert_youtube: 'Converts a YouTube video to markdown by extracting transcript and video metadata. Returns markdown with timestamps. Use this to summarize long videos. Requires valid YouTube URL (youtube.com or youtu.be).'
Add formal enums and type constraints to all parameters. Replace 'type' in queue_submit with an enum ['youtube', 'webpage', 'audio', 'document']. Add length/size limits to 'items' in batch_convert (e.g., max 100 items per call). Add URL format validation hints to 'url' parameters.
Document output schemas for all 9 tools. Create a separate section in docstrings listing returned fields, types, and examples. Example: 'Returns: {markdown: str, duration_seconds: int, video_id: str, title: str}'. Include pagination info if results can be large.
Add parameter-level descriptions with format constraints. Replace 'Path to audio file' with 'Path to audio file (supports .mp3, .wav, .m4a; max 500MB; relative or absolute paths). Example: /home/user/podcast.mp3 or ./recordings/interview.wav'.
Implement explicit error handling with recovery hints. Add try/catch blocks and return structured errors like: {error: 'InvalidURL', message: 'URL must start with https:// or http://', suggestion: 'Did you mean: https://youtube.com/...'?}. Document common failure modes in tool descriptions.
Add tool chaining hints in descriptions. If queue_submit returns a job_id, document: 'Returns a job_id (UUID). Pass this to check_job_status() to poll for completion.' Clarify which tools produce outputs that other tools consume.
No output schemas documented. The rubric requires documentation of return types and structures. Code samples do not show what convert_youtube, batch_convert, browser_extract, or crawl_website return. Without output schemas, LLMs cannot plan chaining (e.g., what ID does batch_convert return for status polling?) or extract relevant fields. This forces agents to guess structure.
Parameter descriptions missing or insufficient. Most parameters have only 1-2 word descriptions ('YouTube video URL', 'Path to audio file'). Production baseline is 72 chars per param. No guidance on format constraints (URL validation, file path validation), no hints about required vs optional, no dependency documentation (e.g., 'type' param in queue_submit controls what's expected in 'url' but this is not documented).
No error handling or recovery guidance. No evidence of try/catch, validation, or error categorization in provided source. No guidance on what happens when a YouTube URL is invalid, an audio file is corrupted, or a webpage is unreachable. No recovery hints (e.g., 'If audio_file.mp3 fails, try with audio_file.wav'). Agents will receive raw exceptions without context.
No tool chaining hints. batch_convert, queue_submit, and browser_navigate are WRITE tools that likely produce job IDs or operation references, but there's no indication what tools consume those outputs. For example, does queue_submit return a job_id that can be passed to a status_check tool? This forces agents to guess and wastes turns.
batch_convert has an 'items' parameter typed as array with no inner schema. No documentation of what each item should contain, what fields are required, what format is expected. This is ambiguous, items could be URLs, file paths, objects with metadata, etc. The LLM has no guidance.
queue_submit 'type' parameter lists allowed values in description ('youtube, webpage, audio, document') but not as formal enum. LLMs are more reliable with enum constraints than free-text descriptions. Hallucinated values like 'video' or 'pdf' could slip through.
No pagination or result limits documented. crawl_website could return hundreds of pages; no indication of limits, offsets, or cursor-based pagination. batch_convert could process thousands of items; no guidance on size limits. This risks context window exhaustion.
Tool naming could be more precise. 'convert_*' tools are clear, but 'browser_navigate' and 'browser_extract' suggest a persistent browser state, unclear if state persists across calls or if each call is stateless. 'crawl_website' is ambiguous (shallow crawl? deep? BFS? DFS?). More specific names like 'convert_youtube_to_markdown', 'browser_goto_and_wait', 'crawl_website_depth_limit' would reduce ambiguity.
No documentation of idempotency. WRITE tools like batch_convert, browser_navigate, and queue_submit should declare idempotency guarantees. If an agent retries a failed batch_convert, will it duplicate entries? This is critical for agent reliability.
batch_convertbrowser_navigatequeue_submit
Specify pagination and result limits. For crawl_website, add: 'Returns up to 50 pages by default. Use max_depth parameter (1-5) to control crawl depth. Use cursor parameter for subsequent pages.' Document the structure of cursor/pagination tokens.
Clarify browser state persistence. Rename browser_navigate and browser_extract to make it clear if they operate on a shared browser session or independent requests. Example: browser_goto_url (opens fresh tab) vs browser_extract_from_current (extracts from active tab).
Document idempotency guarantees. Add to batch_convert: 'Idempotent: retrying with the same items array will not create duplicate conversions if the job already completed. Uses content hash to detect duplicates.'
Add examples of valid inputs and outputs to tool descriptions. Show example YouTube URL format, example file path, example batch items structure (if known from implementation).
Declare permissions and security scope. Add a 'scope' or 'permissions' field to tool definitions (if supported by fastmcp). Example: convert_youtube requires 'read:external'. queue_submit requires 'write:jobs'.
Add timeout and retry guidance. Specify: 'This tool may take 10-60 seconds for large files. If it times out, retry up to 3 times. If it fails after 3 retries, the file may be corrupted.'
Split batch_convert into batch_convert and batch_convert_status if status polling is a separate operation. Currently unclear if batch_convert is synchronous or returns a job_id.
Document mutually exclusive parameters if any exist. If browser_navigate could accept either 'url' or 'back' action, state: 'Use either url (to navigate to new page) OR action='back' (to go back); not both.'
Add discovery hints. For example: 'Call list_supported_formats() first to see all supported input formats before calling convert_document.' (if such a discovery tool exists or should exist).