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

Annotations already mark the tool read-only and closed-world. The description adds that it returns ids rather than full records, that results are scoped to the caller's own program, and that a Pro plan or higher is required. Ranking, result limits and pagination are not covered.

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 sentences, front-loaded with purpose, each earning its place. There is no redundancy.

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?

This is a simple one-parameter read tool with an output schema and annotations. The description covers scope, searchable fields, the output relationship to fetch and the plan requirement. Little else is needed.

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?

The schema describes query only as search text of at least 2 characters. The description adds which fields the text matches: names, emails, coupon codes, order ids and customer names. That tells the agent what kinds of query strings are meaningful.

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?

States a specific verb and resource: free-text search over the caller's own LinkJolt affiliate program. It enumerates the searchable entities (campaigns, affiliates, coupons, conversions), which sets it apart from list_* and get_* siblings. It also names its relationship to fetch.

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?

Opens with "Use this to find records... by free text" and explains that results feed into the fetch tool, which is a clear workflow. It also states the Pro plan prerequisite. It does not say when to prefer list_affiliates, list_coupons and similar tools for structured enumeration over free-text search.

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