ken-cavanagh-glean/fieldkit

Overview

This skill helps you design and optimize tools that language-model agents use to interact with systems. It focuses on clear tool contracts, consolidation versus separation, and response/error formats that enable reliable agent behavior. Use it to create tool descriptions, reduce ambiguity, and choose when to simplify or consolidate tool sets.

How this skill works

The skill inspects tool APIs and descriptions to ensure they answer what the tool does, when to use it, what inputs it accepts, and what it returns. It evaluates naming, defaults, response verbosity options, error messages, and namespacing to reduce agent confusion and context usage. It can recommend consolidation or architectural reduction when appropriate and propose improved description text and examples for agent consumption.

When to use it

• Creating new tools or APIs intended for use by language-model agents
• Debugging repeated tool-selection or misuse failures in agent runs
• Optimizing an existing tool collection to reduce ambiguity and tokens
• Deciding whether to consolidate multiple narrow tools into a single comprehensive tool
• Evaluating third-party tools for safe and effective agent integration

Best practices

• Write descriptions that explicitly state what the tool does, when to use it, inputs (types and defaults), and expected outputs
• Prefer consolidated tools for end-to-end workflows unless behaviors are fundamentally different
• Provide concise and detailed response formats and let agents choose verbosity
• Design actionable error messages that include how to recover or correct inputs
• Use consistent naming conventions (verb-noun) and parameter names across tools
• Limit tool count (rough guideline: 10–20) and use namespacing to organize larger sets

Example use cases

• Replace several narrow CRUD endpoints with a single scheduling tool that handles discovery and creation
• Convert vague database search tools into a well-typed get_customer(customer_id, format) with clear errors
• Audit a tool collection to remove overlapping functionality and reduce agent selection errors
• Implement concise/detailed response options to control token usage in multi-step reasoning
• Use an agent to analyze failure logs and iteratively improve tool descriptions and defaults