agent-tools

A Claude Code skill for designing Unity Catalog SQL functions exposed to AI agents via managed MCP on Databricks.

Distilled from a paired empirical study: six hypothesis families, n=200 paired per cell, 6,400 total paired rows on databricks-claude-sonnet-4-6 plus cross-tier robustness on databricks-claude-haiku-4-5.

Headline. Cost responds to design (every cost CI signed, most exclude zero); accuracy mostly does not (no comparison clears p<0.05; bad function names closest at p=0.09). Four levers ranked: count >> name > COMMENT ≈ schema.

📖 Companion article: Designing UC Functions Agents Actually Use Well — <MEDIUM_URL_HERE> (replace with link after publication).

What's inside

The skill at skills/agent-tools/SKILL.md covers seven Databricks-native principles:

1. Granularity-as-governance — UC function = GRANT boundary.
2. The DML split — make_agent_tools factory pattern for writes.
3. COMMENT-as-prompt — ALTER FUNCTION as the iteration loop.
4. Schema-as-namespace, catalog-as-tenant.
5. Managed MCP collapses tool server into function definition.
6. Errors that teach — typed hint rows over silent failures.
7. Surface hygiene — co-located schemas are the dominant cost lever (H4 + H6: +33-40% tokens at flat accuracy).

Plus five Databricks-specific engineering patterns (Vector Search foldable params, SQL-over-Python, ai_query() inside UC fns, self- describing fn_schema, API-style versioning), a drop-in template, and a verification checklist.

Install as a Claude Code plugin

# One-session, no marketplace registration:
claude --plugin-dir /path/to/agent-tools

# Or register as a marketplace, then install:
claude plugin marketplace add https://github.com/philtief/agent-tools
claude plugin install agent-tools@philtief

Validate the manifest before committing changes:

claude plugin validate /path/to/agent-tools

When the skill triggers

• "Create a UC function for an agent / Genie space / MCP tool"
• "Add a tool to my agent — implement it as a UC function"
• "Review my fn_* SQL function"
• "Should this be one tool or several?"
• "How should I write the COMMENT for this function?"
• "My agent keeps picking the wrong tool — fix the function descriptions"

License

Apache 2.0. See LICENSE.