find_skill

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

Annotations already declare a safe read operation, and the description adds substantial behavior beyond them: the ranking sources, that results are ranked by name and description, that at most 3 matches are returned with skill_id and a match reason, and what an empty matches list signifies. It also discloses the default scoping behavior when project_id is omitted.

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 purpose and trigger are front-loaded, and the return-value semantics close the description. The long enumeration of example task types is useful but bulky, and the 'No project_id is needed' sentence partially duplicates the Args entry for project_id.

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?

There is no output schema, so the description supplies the return contract itself: up to 3 matches, each with skill_id and a match reason, plus the meaning of an empty result. Combined with the scoping rules and examples, an agent has everything needed to call it correctly.

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?

With schema description coverage at 0%, the description carries the full burden and largely does: task is defined as the user's goal in their own words with an example, and project_id is explained as optional, limiting project skills to a single project while omitting it searches all accessible projects. It does not discuss task phrasing length limits or how vague inputs are handled.

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 opens with a specific verb and resource ('Search the user's saved skills ... for a task') and scopes the corpus precisely: built-in skills, Unilytics skills, the user's own skills and project skills. This clearly separates it from retrieval-style siblings like get_skill or list_skill_proposals, which do not do task-based matching.

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 an explicit trigger ('Use when the user asks for a task their saved skills may cover') plus a concrete list of qualifying task types such as keyword research, site audits and content briefs. It also supplies an implicit when-not via 'An empty `matches` means no saved skill fits the task', but it never names a specific alternative tool for cases where skill search is the wrong choice.

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