This server exposes 13 read-only tools for querying Lightdash analytics projects. Tool names follow verb_noun convention (list_, get_) and are clear. Descriptions are present but minimal (10-80 chars), falling below the 194-char baseline average for A+ tools. All tools have input schemas with proper types and descriptions. However, the server lacks output schema documentation, error handling guidance, and structured recovery instructions. Tools are simple pass-throughs to the Lightdash API with no evidence of response shaping, result limiting, or pagination guidance. Security is adequate (read-only, API key injected via environment) but not explicitly documented in tool descriptions.
Missing output schema documentation. No documentation of what fields are returned by any tool. LLMs cannot plan downstream calls or extract required data without knowing response structure (e.g., what fields does lightdash_list_projects return? Does it include project_id, name, description?). This violates pattern:response-shaper and forces LLMs to guess field names.
Tool descriptions are too brief (10-50 chars). Average is 35 chars vs. 194-char baseline for A+ tools. Examples: 'List all projects in the Lightdash organization' (50 chars), 'Get details of a specific project' (35 chars), 'List all spaces in a project' (29 chars). These lack WHEN to use, prerequisites, or relationship to similar tools. Descriptions should explain: What does it return? When should the LLM call it instead of get_catalog? What are the prerequisites?
Recommendations
Add output schema documentation for all 13 tools. For each tool, document the response structure: property names, types, and what each field represents. Example: 'Returns an object with properties: projects (array of {id: string, name: string, description: string, created_at: ISO8601}).'
Expand tool descriptions to 100-200 chars. Include: (1) What the tool returns, (2) When to use it vs similar tools, (3) Prerequisites (e.g., 'Call lightdash_list_projects first to obtain a projectUuid'). Example: 'Lists all spaces (folders) within a project. Call lightdash_list_projects first to get the projectUuid. Spaces are containers for charts and dashboards.'
Add pagination parameters to list tools. Modify lightdash_list_projects, lightdash_list_spaces, lightdash_list_charts, and lightdash_list_dashboards to accept optional limit (default 20, max 100) and offset (default 0) parameters. Document in the tool description: 'Supports pagination. Default limit is 20 items. Use offset to fetch subsequent pages.'
Support human-readable identifiers. Extend lightdash_get_project, lightdash_list_spaces, lightdash_list_charts, lightdash_list_dashboards, and metadata tools to accept an optional project_name parameter (in addition to projectUuid). Internally, if project_name is provided and projectUuid is not, call lightdash_list_projects to resolve the name to a UUID.
Add tool annotations. Update all tool definitions to include readOnlyHint=true and idempotentHint=true. This signals to agents that these tools are safe to call repeatedly and do not modify state.
No error handling guidance. Tools lack descriptions of what happens on failure (e.g., invalid projectUuid, API rate limit, network timeout). Error responses do not tell the LLM what to do next: retry? Try a different parameter? Is the project UUID format wrong? Agents receive raw HTTP errors with no recovery instructions.
No pagination or result-limiting guidance. List tools (list_projects, list_spaces, list_charts, list_dashboards) do not document maximum result count, pagination mechanism (offset/limit, cursor), or whether results are capped. If Lightdash returns 500 spaces, the entire response enters the LLM context, wasting tokens and degrading reasoning. Rubric baseline: list tools should accept page/offset/limit and return total count or next_cursor.
Parameter 'projectUuid' requires opaque system IDs, forcing extra lookup calls. Rubric guidance: 'Accept human-friendly identifiers (email, username) alongside system IDs.' Tools like lightdash_get_project, lightdash_list_spaces, etc. require projectUuid but do not accept project_name. Users say 'Show me the spaces in my Sales project', the agent must call lightdash_list_projects, parse the response to find the UUID, then call lightdash_list_spaces. This two-step requirement wastes tokens and invites errors. Tools should accept both projectUuid AND project_name, resolving names to UUIDs internally.
No tool annotations for read-only hints. MCP spec (current, 2026-07-28) supports tool annotations including readOnlyHint, destructiveHint, and idempotentHint. All 13 tools are read-only and idempotent, declaring this via annotations improves agent safety and planning. Currently, the LLM must infer read-only from description text.
Ambiguous tool distinctions. Similar tools lack clear usage guidance: lightdash_get_catalog vs lightdash_get_metrics_catalog? lightdash_get_charts_as_code vs lightdash_list_charts? Rubric: 'When multiple tools operate on the same resource, their names must make the distinction obvious.' Descriptions should explain the difference (e.g., 'Returns the full data catalog as a structured object' vs 'Returns only metric definitions'). Without this, LLMs conflate tools and call the wrong one.
Document error conditions. For tools accepting projectUuid (get_project, list_spaces, etc.), add to the description: 'Returns an error if the projectUuid is invalid or the project does not exist. Verify the UUID via lightdash_list_projects.'
Clarify overlapping tool purposes. Add to get_catalog: 'Returns the full data catalog including tables, fields, and metrics in a structured format.' Add to get_metrics_catalog: 'Returns only metric definitions, not tables or fields. Faster if you only need metrics.'
Add per-parameter guidance. The projectUuid parameter appears in 11 tools. Add a shared note in the server documentation or tool description template: 'projectUuid is the unique identifier for a Lightdash project. Obtain it from lightdash_list_projects.'
Consider batch variants. If agents frequently call lightdash_get_metadata for multiple tables, offer lightdash_get_metadata_batch(projectUuid, tables: string[]) to reduce round-trips and token waste.