I Tried to Assign Tasks to an AI. Turns Out I Didn't Know What It Could Do.

Short summary

Dispatching work to AI agents without formal capability specs is just guessing—a cognitive trap where confidence masks ignorance. The author built a task router for multiple agents but couldn't articulate what each could actually do. They discovered the AgentSpec framework, which advocates typed capability specifications with preconditions and limits. Write a formal spec for tools you collaborate with frequently (conditions for effectiveness, known limits, failure modes) to uncover dangerous gaps between what you assume you know and what you actually know.

• •Capability specs prevent silent failures; vague mental models of tool capabilities breed confidence-masked guessing
• •Write a formal spec for your most-used tools: document success conditions, known limits, failure modes, and unsupported task types
• •The act of writing specs surfaces dangerous gaps between what you think you know and what you actually know

Generated with AI, which can make mistakes.