Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
This server exhibits significant definition quality gaps across nearly all dimensions. Tool names follow verb_noun conventions (list_, get_, run_, create_, toggle_), which is positive, but descriptions lack depth and context. Input schemas are present and typed, but descriptions are minimal, most parameter descriptions are under 30 characters and fail to explain WHEN to use the tool or what happens on errors. Output schemas are completely undocumented, the code shows handlers returning structured objects (e.g., { scenarios }, { success: true, executionId, message }), but no formal schema definitions are visible in the tool registration. Error handling is basic, generic error messages like 'Nie udało się pobrać scenariuszy' provide no guidance for LLM recovery. The server exposes credentials (MAKE_API_TOKEN) via environment variables correctly, avoiding parameter leakage, but lacks audit logging, permission gates, and rate limiting. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present despite the code explicitly identifying write vs. read-only operations.
Output schemas completely undocumented. Handler functions return structured objects (e.g., { scenarios }, { success, executionId, message }) but no JSON Schema definitions are present in tool registration or comments. LLMs cannot know what fields to expect or plan downstream calls.
Parameter descriptions are generic and under 30 characters (most are 10 - 20 chars like 'ID scenariusza'). Descriptions fail to explain WHEN to use the tool, what data formats are expected, what happens on success/failure, or how the parameter relates to similar tools. Baseline: A+ tools average 72 chars per param description.
Expand tool descriptions from ~20 chars to 80 - 150 chars. Include: what the tool does, when to call it instead of similar tools, what it returns, and any prerequisites. Example: 'list_scenarios: Fetches all scenarios (automation workflows) you have access to. Call this first to discover available workflows before querying details. Returns an array of scenario summaries with id, name, status, and last_run. Note: Large result sets may be truncated; use pagination if needed.'
Add explicit JSON Schema output definitions to each tool. Include in tool registration or as inline comments. Example for list_scenarios: { type: 'object', properties: { scenarios: { type: 'array', items: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' }, active: { type: 'boolean' }, lastRun: { type: 'string', format: 'date-time' } }, required: ['id', 'name'] }, total: { type: 'integer' } }, required: ['scenarios'] }
Expand parameter descriptions from ~15 chars to 50 - 80 chars. Specify format, range, and valid values. Example: 'scenarioId: The unique ID of the scenario (36-char UUID format, e.g. 550e8400-e29b-41d4-a716-446655440000). Obtain from list_scenarios or create_scenario.' and 'limit: Maximum number of history entries to return (integer, 1 - 100, default 10). Higher values return more historical data but increase response size.'
Add tool annotations to the tool registration objects. Add fields: readOnlyHint: true for list_scenarios, get_scenario, list_apps, get_scenario_history; destructiveHint: true for run_scenario (triggers external action) and toggle_scenario (disables workflows); idempotentHint: true only for get_* tools. This lets LLMs determine which calls are safe to retry.
Tool descriptions are too brief (18 - 25 characters in Polish, roughly 25 - 40 in English). Descriptions like 'Pobiera listę wszystkich scenariuszy w Make' (Gets list of all scenarios in Make) do not explain when to call this tool vs. get_scenario, what the result contains, or dependencies. Baseline: A+ tools average 194 chars; critical minimum is 50 - 100 chars for adequate context.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite explicit read/write classification in the risk field. LLMs cannot determine which operations are safe to retry or have side effects. run_scenario, toggle_scenario, and create_scenario are marked WRITE but lack destructiveHint/idempotentHint annotations.
Error handling is generic and non-actionable. Handlers throw errors like 'Nie udało się pobrać scenariuszy: <error.message>' with no guidance on recovery (retry? lookup first? ask user?). No error categorization (retryable vs. user-fixable vs. fatal). Try search_users() with a partial name.'
No input validation beyond parameter presence checks. The create_scenario handler checks if 'name' is set but does not validate length, character restrictions, or encoding. toggle_scenario accepts a boolean 'active' but does not validate the scenarioId format or existence. No input sanitization against injection attacks (though severity is reduced because parameters go to API, not SQL/shell).
create_scenario accepts an optional folderID parameter with no description of valid format, length, or whether it is required for all scenarios. No guidance on what happens if the folder does not exist.
get_scenario_history accepts an optional 'limit' parameter (default 10) but the description does not specify min/max bounds. Is 1 allowed? 1000? 1,000,000? No upper bound invites LLM to pass absurd values. Baseline: A+ tools specify constraints like 'page_size 1 - 100, days 1 - 365'.
No pagination support in list_scenarios or list_apps despite these being discovery tools that may return large result sets. Rubric: 'Tools returning lists should accept page/offset and limit parameters and return a total count or next_cursor. Without pagination, large results blow the context window.' Current handlers return raw API responses without limiting or structuring for LLM consumption.
API responses are not trimmed or shaped for agent consumption. Handlers return raw API payloads (e.g., response.data from axios calls) which likely contain verbose metadata, internal fields, and audit data irrelevant to the chat context. Rubric: 'Strip pagination internals, audit fields, and raw IDs the user never sees. High token count dilutes signal, risks exhausting the context window, and increases hallucination likelihood.'
No logging, audit trail, or permission checks. The server has no mechanism to log who (which agent/user) called which tool with which parameters, when, and what the outcome was. Rubric: 'Log who called what tool, with which parameters, at what time, and what happened. Agent-initiated actions must be traceable for compliance, debugging, and incident response.' The server also has no permission gates to verify the calling agent has authority to execute sensitive operations like toggle_scenario or delete-like actions.
No rate limiting or timeout guards. An agent in a retry loop could hammer the Make API with thousands of requests per minute. No explicit timeouts on axios calls (default Node.js timeout is 120s, which is long). Rubric: 'Apply rate limits to prevent runaway agents from overwhelming downstream services.' and 'Set explicit timeouts for tools that call external services.'
Implement proper error handling with actionable recovery guidance. Replace generic throws with structured error objects including: error code (e.g., 'SCENARIO_NOT_FOUND'), message, suggestion. Example: { error: 'SCENARIO_NOT_FOUND', message: 'Scenario 550e8400-... does not exist.', suggestion: 'Call list_scenarios() to see available scenarios, or verify the scenario ID is correct.' }
Trim and shape API responses before returning to the LLM. Example: for get_scenario, extract only: id, name, active, description, lastRun, teamId. Omit audit fields, raw metadata, and internal API details. Every extra field wastes tokens and dilutes signal.
Add tool scope declarations. Register each tool with required permissions. Example: list_scenarios requires 'read:scenarios'; run_scenario requires 'execute:scenarios'; create_scenario requires 'write:scenarios'. This enables least-privilege agent configuration and clear audit trails.
Implement comprehensive audit logging to stderr or structured logs (JSON format). Log: timestamp, agent_id (if available), tool_name, parameters (excluding secrets), result (success/error), latency. This is non-negotiable for compliance and debugging.
Add permission gates before executing write operations. Before run_scenario, toggle_scenario, or create_scenario, verify the calling context has the required scope. Return a clear error if permissions are insufficient: { error: 'PERMISSION_DENIED', message: 'Agent does not have execute:scenarios permission.' }
Set explicit timeouts on all axios calls. Add to the axios config: timeout: 10000 (10 seconds for most calls, 30 seconds for long-running execute operations). Return a timeout error with retry guidance: { error: 'TIMEOUT', message: 'Request to Make API timed out after 10s. This may indicate a network issue or the Make service is slow. You can retry in a few seconds.' }
Implement rate limiting (e.g., using express-rate-limit or similar). Example: 100 requests per minute per agent. Return 429 Too Many Requests with: { error: 'RATE_LIMITED', message: 'Rate limit exceeded (100 req/min). Wait at least 30 seconds before retrying.' }
Document dependencies between tools. Example: 'If you only have a scenario name, call list_scenarios() first to obtain the scenario ID, then pass it to get_scenario().' Add this to tool descriptions.
Validate the folderID parameter in create_scenario. Accept optional folderID as a UUID string. Document: 'folderID: Optional folder UUID where the scenario will be created (36-char UUID format). If omitted, the scenario is created in the root folder. Obtain from a folder listing tool (not yet implemented).' Return a clear error if the folder does not exist: { error: 'FOLDER_NOT_FOUND', message: 'Folder 550e8400-... does not exist. Call list_folders() to see available folders.' }
Specify bounds for the limit parameter in get_scenario_history. Update description: 'limit: Maximum number of history entries to return (integer, 1 - 100, default 10). Requests exceeding 100 are capped at 100 to prevent excessive memory use.'
Handle API errors gracefully and return schema-compliant responses even on failure. Instead of throwing, return: { error: 'API_ERROR', statusCode: 500, message: 'Make API returned HTTP 500. This is likely a temporary service issue. You can retry in a few seconds.', retryable: true }. This lets LLMs decide whether to retry.
Translate tool descriptions and parameter descriptions into English or provide bilingual support. The current Polish descriptions ('Pobiera listę...', 'Włącza lub wyłącza...') make the server less accessible to non-Polish-speaking LLM users and may confuse multilingual agents. Use consistent English naming and descriptions across all tools.