Connect to an API (one-time setup)

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses behavioral traits beyond the annotations: it mentions side effects ('makes outbound HTTP(S) requests to url, calls the configured LLM, and persists the adapter + any credentials under ~/.liquid') and confirms idempotency in a user-friendly way ('reuses the existing adapter instead of duplicating it'). This meets the high bar for transparency even with good annotations, as it adds context about persistence and auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the main purpose. It contains several sentences, each adding value (e.g., side effects, idempotency, alternatives). While slightly longer than minimal, every sentence is justified and no redundancy is present. Could be slightly tighter, but overall effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, side effects, idempotency, output schema with adapter_id), the description covers all necessary context: usage, behavior, parameter details, return value, and alternatives. It also notes credentials storage. The description is complete enough for an AI agent to understand when and how to use the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema coverage, the description adds significant meaning: for url, it explains it accepts GraphQL, WSDL, gRPC, or WebSocket targets (not in schema). For target_model, it clarifies it must be a flat map with examples. For credentials, it states they are stored encrypted under ~/.liquid and applied automatically. This enriches the parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'One-time setup for an API.' It specifies the actions: discovers the API at a URL, maps responses to a target model, and saves a reusable adapter, returning an adapter_id. It distinguishes from siblings by explicitly naming liquid_discover (quick look without saving) and liquid_fetch (reading from an already-connected API), making the purpose unique.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Use this once per API.' It tells when to use an alternative: 'For a quick look without saving anything, use liquid_discover instead; to read data from an already-connected API, use liquid_fetch.' This clearly delineates when to use this tool versus its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.