The Maket server exposes 14 tools with extremely minimal definition quality. Based on static code analysis of the provided source, NO tool schemas are visible in the TypeScript files referenced (packages/server/src/tools/*.ts files are not included in the provided source code). Tool descriptions exist but are extremely brief (7-35 characters), providing minimal context for LLM selection. No parameter descriptions, type information, or output schemas are documented in the available source. The server appears to be a visual design tool with write-heavy operations (assets:upload, documents:create, canvas:update, gmail:send) but lacks the safety documentation required for destructive tools. With names like 'workspace:command' and 'state:update', several tools have ambiguous purpose. The HTTP transport is appropriate, but definition quality is far below production standards.
NO INPUT SCHEMAS VISIBLE: Tool definitions reference packages/server/src/tools/*.ts files, but actual schema code is not provided in source. All 14 tools lack documented input schemas, parameter types, and descriptions.
MINIMAL DESCRIPTIONS: Tool descriptions range from 7 - 35 characters ('Create and render Mermaid diagrams', 'Send emails via Gmail'). LLMs cannot distinguish similar tools or understand when to select them.
ADD COMPLETE INPUT SCHEMAS to all 14 tools with proper JSON Schema: type, description, enum/pattern/min-max constraints, required/optional status. Example for mermaid:diagram: { type: 'object', required: ['diagram_type', 'diagram_definition'], properties: { diagram_type: { type: 'string', enum: ['flowchart', 'sequence', 'class', ...], description: 'The type of Mermaid diagram to create' }, diagram_definition: { type: 'string', description: 'The Mermaid diagram syntax (e.g., graph TD: A --> B)' }, ... } }
EXPAND TOOL DESCRIPTIONS to 100 - 200 characters. Current descriptions like 'Create and render Mermaid diagrams' lack context. Better: 'Create and render Mermaid diagrams (flowcharts, sequence, state, class, ER). Returns SVG/PNG. Use when the user requests a visual flowchart or diagram.' This tells LLMs WHAT, WHEN, and WHAT you get.
CLARIFY AMBIGUOUS NAMES: Rename 'workspace:command' to either 'workspace:execute_command', 'workspace:create', 'workspace:configure', or split into multiple tools with clear names. Rename 'state:update' to 'document:update_state' or split into 'canvas:update_state' + 'document:update_state'.
ADD PARAMETER DESCRIPTIONS to all parameters. For each param in the schema, add a description field explaining what it controls, expected format, and valid range. Example: 'diagram_type: The Mermaid diagram type (one of: flowchart, sequence, class, state, er). Defaults to flowchart.'
DOCUMENT OUTPUT SCHEMAS for all tools. For each tool, specify what fields are returned. Example for assets:upload: '{ asset_id: string (UUID), asset_url: string (HTTPS), file_size: number (bytes), created_at: ISO8601 timestamp, content_type: string (MIME) }'
AMBIGUOUS TOOL NAMES: 'workspace:command' is vague, does it create workspaces, execute shell commands, modify workspace settings, or list workspace members? 'state:update' could mean document state, UI state, or component state. Per pattern:tool, names must start with clear action verbs (create_, update_, delete_, search_, list_, get_, send_) and unambiguously convey what happens when called.
NO PARAMETER DOCUMENTATION: Tool parameter names, types, descriptions, constraints (enum, min/max, regex), and required/optional status are not visible in provided source. Without this, LLMs cannot reliably construct valid calls.
NO OUTPUT SCHEMA DOCUMENTATION: Tool return types are completely undocumented. Per pattern:tool and mxe:response-field-naming, LLMs need to know what fields to expect (e.g., does assets:upload return asset_id, asset_url, or both?) so they can plan downstream calls and extract the right data.
DESTRUCTIVE TOOLS LACK SAFETY DOCUMENTATION: assets:upload, chartes:create, documents:create, canvas:update, pages:manage, state:update, and gmail:send are write/destructive operations. Per pattern:confirmation-request and pattern:command-tool, these must declare that they modify state and document error recovery paths. No dry-run, idempotency markers, or recovery guidance visible.
gmail:send LACKS SECURITY DOCUMENTATION: A tool that sends emails via Gmail should document whether API credentials are injected server-side or expected as parameters. Per pattern:secret-injection, credentials must NEVER be tool parameters. No audit trail or scope declaration (e.g., 'requires gmail.send scope') visible.
NO ERROR HANDLING GUIDANCE: None of the tool descriptions document error conditions, recovery paths, or actionable error messages. Per pattern:recovery-guide, LLMs need to know: Is this error retryable? Should I ask the user? Or is it fatal? No guidance provided.
ADD IDEMPOTENCY/DRY-RUN SUPPORT to write-heavy tools (assets:upload, documents:create, canvas:update, gmail:send). Add a dry_run boolean parameter and document: 'If dry_run=true, validate the operation but do not persist changes.' Document idempotency marker (e.g., 'idempotent if asset_id is stable for the same file hash') in tool description.
DOCUMENT ERROR SCENARIOS: Add to each tool description a brief error section. Example for gmail:send: 'Errors: missing_recipient (user not found, call search_users first), invalid_email (malformed address), quota_exceeded (retry after 60s), auth_failed (check credentials).'
SECURE GMAIL:SEND: Document that Gmail credentials are injected server-side via environment or vault, NEVER passed as parameters. Declare required scope: 'Requires gmail.send permission.' Add audit note: 'All send operations are logged with recipient, timestamp, subject for compliance.'
ADD TOOL ANNOTATIONS (per CURRENT spec) to help clients understand side effects: Destructive tools (assets:upload, documents:create, canvas:update, gmail:send) should declare destructiveHint=true. Read-only tools (mermaid:diagram, html:render, learn:fetch, pdf:export) should declare readOnlyHint=true. Idempotent tools should declare idempotentHint=true.
PROVIDE DISCOVERY & CHAINING SUPPORT: If documents:create returns document_id, ensure all downstream tools (canvas:update, pages:manage) accept document_id. If collections:list returns collection_ids, downstream tools should accept them. Document these dependencies in descriptions.