When an agent scans a tool catalogue, it does not read your code and it does not click your demo. It reads the description in the manifest — usually a single sentence — and decides. That sentence carries more weight than any other piece of documentation you write.
What a good description contains
- What it does — one concrete verb phrase. "Convert a HEX color to RGB and HSL" beats "Color utilities for developers."
- When to use it — the situation the tool is built for. "Use when you need to compare two texts and see line-level differences."
- What it does not do — if the boundary matters. "This tool checks syntax only; it does not execute code."
- Input expectations — units, formats, and constraints the schema may not fully convey. "Expects a 24-bit HEX string with or without #."
Two common failure modes
The first is the marketing description: "A powerful, comprehensive, enterprise-grade text solution." It contains no information the model can act on. The second is the overloaded description: listing every edge feature until the primary purpose is buried. Both produce the same result — the model picks the wrong tool or invents parameters.
A practical check
Before publishing a tool description, ask: if a competent engineer read only this sentence and had to call the tool correctly, would they succeed? If the answer is no, rewrite it. The site's manifest descriptions follow this rule, and it is the reason the manifest works as a contract rather than a brochure.
