search_skills

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds real context: the search target is a public GitHub-hosted repository (consistent with openWorldHint), and results are pointers that must be fetched with load_skill rather than full skill bodies. It does not mention ranking, pagination or rate limits.

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?

Three short sentences, front-loaded with what it searches and where, followed by the browse case and the follow-up tool. No filler, no restatement of the tool name or annotations.

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?

For a two-parameter read-only search with no output schema, the description covers purpose, the empty-query behavior and the read follow-up, which is enough to call it correctly. The only loose end is the undocumented 'limit' parameter, whose default and cap of 30 live in the schema but carry no explanation of ordering or result-count tradeoffs.

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?

Schema coverage is 50%: the 'query' parameter already documents itself as keywords or empty-to-browse, so the description's wording largely mirrors the schema. The description does add the match fields (name, description, content) which the schema omits, but the 'limit' parameter is left entirely unexplained in both places, keeping this at the baseline.

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 states a specific verb and resource ('Find Vapi agent skills') and names the exact repository, scope and match fields (name, description, content). It also distinguishes itself from the sibling that consumes its output ('Use load_skill to read a result'), so an agent can separate search from read without opening either schema.

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?

It gives a concrete usage condition ('Omit query to browse') and routes the agent to the correct follow-up tool (load_skill) for reading a hit. It stops short of an explicit 'do not use this for X' exclusion or guidance on when to prefer ask_vapi_docs, so it is clear but not fully exhaustive.

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