This server has 15 tools with schemas and descriptions present, but suffers from significant quality gaps. 10 tools (workers_*) are explicitly defined with JSON schemas and descriptions in index.js. 5 tools (voicenotes_*) are listed in the briefing but NOT visible in the provided source code, they appear only in examples/voicenotes-worker.js (not shown). The workers_* tools have adequate schemas and descriptions (averaging 120-150 chars), meeting baseline minimums but lacking LLM-optimized depth. Parameter descriptions are present but minimal (20-50 chars), leaving room for constraint details and actionable guidance. Error handling is absent, the cfApiCall helper throws generic 'CF API Error' messages with no recovery guidance. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels assigned. No structured output documentation. Security concern: CF_API_TOKEN and CF_ACCOUNT_ID are injected server-side (correct), but there is no per-request permission gating or audit logging. Overall: functional baseline with room for maturity.
5 voicenotes_* tools not visible in provided source code (only listed in briefing). Cannot verify input schemas or descriptions. Average score for these tools: 38.6, capped due to missing source evidence.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Risk levels are clear (WRITE, DESTRUCTIVE, READ_ONLY assigned in briefing) but not declared in the tool definition. LLMs cannot infer safety constraints from descriptions alone. Per current spec (2026-07-28), tool annotations are a key signal for agent reasoning.
Verify and include source code for voicenotes_* tools or mark them as unavailable. If they exist in examples/voicenotes-worker.js, provide the full implementation so their schemas and descriptions can be evaluated.
Add tool annotations to all tools: use readOnlyHint for READ_ONLY tools (workers_script_get, workers_scripts_list, workers_route_list, workers_tail_start), destructiveHint for DESTRUCTIVE tools (workers_script_delete, workers_route_delete, workers_secret_delete), and idempotentHint for WRITE tools if applicable. Example: {name: 'workers_script_delete', ..., destructiveHint: true}.
Implement structured error responses with recovery guidance. Instead of throwing 'CF API Error: {raw}', catch API errors and return actionable messages: 'Authentication failed: verify CF_API_TOKEN is valid and has workers:write scope' or 'Worker not found: call workers_scripts_list to see available workers'. Map common Cloudflare error codes (10000=invalid token, 7000=not found, 6003=access denied) to LLM-friendly guidance.
Add output schema documentation in tool descriptions or as a 'Returns' section. Example for workers_scripts_list: 'Returns array of scripts with fields: id (string), name (string), created_on (ISO 8601), modified_on (ISO 8601), etag (string). See workers_script_get for full script object structure.' This enables downstream tool chaining.
Implement pagination for workers_scripts_list and workers_route_list: add limit (default 20, max 100) and offset parameters; return total_count and next_offset in responses. Cap results at 50 items per call to prevent context bloat.
Error handling is generic and non-actionable. The cfApiCall helper catches all Cloudflare API errors and throws 'CF API Error: {raw_json}'. LLMs receive only the raw error object with no recovery guidance (e.g., 'Authentication failed, verify CF_API_TOKEN is valid' or 'Worker not found, call workers_scripts_list to find available workers'). Per pattern:recovery-guide, errors must tell agents what to do next.
Parameter descriptions are minimal and lack constraint details. Example: 'script_name' described as 'Name of the worker script (alphanumeric, hyphens, underscores)', format is stated but no length limits or examples. 'limit' in workers_tail_start is described as 'Number of log entries (default 100, max 1000)' but lacks min value. Per pattern:constrained-input, descriptions should include ranges, formats, and valid value sets. Baseline for param descriptions: 72 chars; these average 40-60 chars.
No output schema documentation. Tool handlers return success responses as {content: [{type: 'text', text: JSON.stringify(result)}]}, but LLMs are not told what fields to expect in 'result'. For example, workers_script_get returns raw Cloudflare API output, does it include id, created_on, modified_on, etag? Does workers_scripts_list return pagination info or a flat array? LLMs cannot plan downstream calls without knowing the response structure. Per pattern:response-shaper, document output schemas.
Pagination not implemented. workers_scripts_list and workers_route_list have no offset, page, or limit parameters. If an account has hundreds of workers or routes, responses will be incomplete or oversized, blowing the context window. Per pattern:paginated-result, list tools must support pagination.
No permission gating or audit logging. Credentials (CF_API_TOKEN, CF_ACCOUNT_ID) are injected server-side (correct), but there is no per-request user/agent identity verification, no audit trail of who called what tool when, and no permission checks on destructive operations. Per pattern:scope-declaration and pattern:audit-trail, tools should declare required scopes and log operations for compliance.
No dry-run or confirmation pattern for destructive operations. tools workers_script_delete, workers_route_delete, and workers_secret_delete are DESTRUCTIVE but can be called directly with no warning or user interaction. Per pattern:confirmation-request, agents should be able to preview consequences before committing irreversible changes.
No idempotency guarantees. Workers API calls (e.g., script upload) may succeed but return 2xx with errors in the response body. If an agent retries on any error, it risks duplicate side effects. Per pattern:idempotent-operation, tools should be designed to handle retries safely or document retry boundaries.
Expand parameter descriptions with constraints and examples. Example: script_name should include 'Must be 1-63 characters, alphanumeric + hyphens/underscores only' and 'Example: my-worker, my_worker_v2'. Example: compatibility_date should note 'Must be YYYY-MM-DD and >= 2021-03-01'.
Add a dry-run or confirm_delete pattern for destructive tools. Offer a workers_script_delete_preview tool that returns what would be deleted, or modify workers_script_delete to require a --confirm flag or additional confirm parameter to prevent accidental deletion.
Implement per-request audit logging: log all tool calls with timestamp, tool name, parameters (sanitized to remove secrets), user/agent identity, and result (success/failure code). Write to stderr or an audit file for compliance tracking.
Add permission checks and scope declarations. Define which Cloudflare API permissions each tool requires (e.g., workers_script_upload requires 'account:account_settings:read' + 'workers:write'). Verify at runtime that CF_API_TOKEN has those scopes before executing; fail with a clear message if not.
Document idempotency explicitly for each tool. For workers_script_upload, note 'Idempotent: uploading the same script twice with the same name and content is safe; the second call returns the same result.' For workers_route_create, note 'Non-idempotent: calling with the same pattern and script creates a duplicate route; use workers_route_list to check before creating.'
Implement timeout handling with retry guidance. Set a 30-second timeout on cfApiCall; if it expires, return 'API timeout after 30s, this may be a temporary service issue. Retry after 10 seconds.' instead of a hung agent.
Add natural-identifier support. Allow workers_script_get to accept either script_name (user-friendly) or script_id (internal). Document this: 'Pass either script_name (e.g., "my-worker") or script_id (e.g., "abc123"); name lookup is performed if id is not found.' This matches the chat data model where users say 'my-worker', not 'abc123'.