Bonnard CLI exposes 34 tools via STDIO. While most tools have brief descriptions (50-150 chars), the majority lack input schemas entirely or have severely incomplete parameter documentation. Many parameter descriptions are absent or trivial (e.g., 'Datasource name', 'API key ID'). Output schemas are undocumented across all tools. No error handling guidance is present. The tool interface reflects CLI design patterns rather than LLM-optimized agent patterns, parameter naming is inconsistent (mix of singular/plural, verb_noun inconsistency), and many tools bundle multiple concerns (e.g., 'datasource add' handles 40+ warehouse-specific parameters in one tool). Tools like 'schema' and 'query' have zero parameter descriptions visible. Only tools with explicit TypeScript definitions (e.g., datasource/add.ts) show any schema structure, and even those are incomplete. Per-tool averages range from 20-65, with median ~38.

• Add explicit JSON Schema definitions with type and properties for all 34 tools. Currently, tools like 'schema' and 'query' have zero schema visible.
• Expand parameter descriptions to 50-150 characters, following LLM-optimized patterns. Current descriptions like 'Datasource name' are too generic. Use format: 'What it controls, valid values/range, context of use.'
• Document output schema for every tool. Include fields the agent needs for downstream calls (e.g., deployment_id from deploy, so agent can call diff).
• Refactor 'datasource add' into warehouse-specific tools or use conditional parameter visibility. 40+ params in one tool exceeds cognitive load for LLM routing.
• Add error handling guidance: 'If connection fails, verify credentials and warehouse is reachable. Use datasource test to validate config.'
• Standardize parameter naming: use 'datasource_name' instead of 'name', 'dashboard_slug' instead of 'slug', to avoid ambiguity across similar tools.
• For enum parameters (type, format, status), declare them as enums in schema, not just strings. Example: type must be one of [snowflake, postgres, redshift, bigquery, databricks, duckdb].
• Add destructiveHint, idempotentHint, and readOnlyHint annotations to tool definitions to signal to agents whether operations are safe to retry.
• For tools requiring login (deploy, pull, dashboard deploy, keys create, metabase connect), add prerequisite language: 'Requires: user must be logged in via login tool.'
• Add confirmation step for destructive operations (datasource remove, dashboard remove, keys revoke). Pattern: return 'This will permanently delete X. Confirm: yes/no', guiding agent to confirm before executing.