Output schemas not documented. LLMs cannot infer what fields hotswap, ingest_persona_chat, and ingest_wikipedia return, making it impossible to chain tools or extract relevant data for downstream calls.
No error handling or recovery guidance in tool definitions. The hotswap tool is IRREVERSIBLE (modifies Docker state, clears logs, restarts containers) but includes no confirmation/dry-run safety pattern documentation in the MCP schema, and error cases (e.g., 'modules not found', 'maven build fails') have no prescribed recovery steps.
Ingest tools lack dependency documentation. Users (via LLM agents) cannot tell whether they must have a running Druid instance, whether data is already available, or what happens if the druid_url is unreachable. Descriptions are bare of context.
Parameter descriptions are minimal and lack format/constraint guidance. E.g., 'modules' parameter says 'Explicit Maven module(s) to rebuild' but does not explain valid module format, naming convention, or examples. LLMs cannot infer whether to pass 'druid-core', 'org.apache.druid:druid-core', or a file path.
poll_interval parameter type is 'number' (seconds as float), but no min/max bounds documented. LLMs could pass 0.001 (1ms) or 3600000 (1000 hours), causing timeouts or CPU waste.
Naming convention issue: ingest_persona_chat and ingest_wikipedia use underscores in datasource/dataset names but parameter descriptions do not clarify whether the LLM should use underscores or the literal names. This invites naming mismatch errors.
ingest_persona_chatingest_wikipedia
Recommendations
Add explicit output schema documentation to hotswap, ingest_persona_chat, and ingest_wikipedia. For hotswap, document that it returns {modules_built: [string], jars_deployed: [string], services_restarted: [string], elapsed_seconds: number, dry_run: boolean}. For ingest tools, document that they return {datasource: string, task_id: string, status: string, row_count: number}. This enables agents to extract IDs for follow-up queries.
Enhance hotswap description to explicitly state: 'This tool is IRREVERSIBLE, it modifies the Docker deployment and clears logs. Use --dry-run to preview changes before applying.' Include guidance on when to use it (after committing code changes) and what to do if Maven build fails (check git status, ensure druid-src exists).
Add format and constraint guidance to modules parameter: 'Maven module paths relative to druid-src root, e.g., druid-core, druid-processing, druid-sql. Accepts repeated flags (-m core -m sql) or comma-separated (core,sql). Invalid modules will cause Maven to exit with an error.' This moves from vague to actionable.
Document min_segments parameter constraint for ingest_persona_chat: 'Minimum value: 1, maximum: 256. Controls the number of Druid hash partitions; higher values improve query parallelism but increase segment overhead. Default 5 is typical for test data.'
Add bounds to poll_interval: 'Polling interval in seconds, range 1 - 600. Shorter intervals (e.g., 1 - 5) provide faster feedback; longer intervals (e.g., 30 - 60) reduce API load. Default 10 is recommended.'
Score history
Overall score trend
↓ 22 points across a rubric change (v1 → v2)
16/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
16
2026-07-28+
v2
2026-03-09
F
38
-
v1
Document default druid_url precedence: 'If omitted, defaults to http://localhost:8090. Specify this parameter if your Druid Overlord is deployed on a different host or port. LLM agents should ask the user for the correct URL if tasks fail with connection errors.'
Add per-parameter dependency notes: For ingest tools, state 'Requires a running Druid instance with the configured druid_url accessible. If ingestion fails with connection timeout, verify network access and ask the user to confirm the Druid URL.' This guides agent error recovery.
Document success/failure outcomes for ingest tools: 'Returns {datasource: string, task_id: string, status: "RUNNING"|"SUCCESS"|"FAILED"}. If status is FAILED, the task_id can be passed to a hypothetical get_ingestion_task tool for error details (not yet implemented).'
Add confirmation pattern for hotswap: Indicate that --dry-run should always be called first, and the agent should review the output before calling again with --dry-run=false. Document this requirement in the description so LLM agents know to ask for user confirmation.
Specify error cases and recovery for each tool. E.g., hotswap can fail with: 'druid-src not found' (user should clone source), 'No modules detected' (user should check git status), 'Maven build failed' (user should run `mvn clean install` manually). Ingest tools can fail with: 'Druid URL unreachable' (retry or ask for correct host), 'Datasource already exists' (use a unique datasource name).