Search links

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

Annotations already cover readOnly/idempotent/non-destructive, so repeating "Read-only" earns nothing; however the description adds genuine context beyond the annotations: it discloses the auth requirement (owner/admin secret key) and the data source (workspace links export). The note that status: all surfaces paused/inactive links further clarifies result scope.

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 capability then modes then examples then access requirement; nothing is padded. The opening "Read-only." is largely redundant with readOnlyHint, a minor waste.

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 read-only search tool with full schema coverage and no output schema, the description covers capability, both query modes, result scope, and the auth prerequisite an agent must know before calling. Nothing material is left for the agent to infer.

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 100%, so the baseline is 3, but the description adds meaning by mapping the free-text query to the five searched fields and by framing tag/campaign as exact-match alternatives to the text search, which helps an agent choose between parameters rather than guess.

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 (finds) plus the resource (links) and enumerates the exact searchable fields: slug, title, destination/longUrl, campaign, tags. It also distinguishes the two search modes (free text vs. exact tag/campaign), which differentiates it from list_links, get_link and check_link.

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?

Concrete example intents ("which links point at /summer", "every link tagged diwali", "links in the spring campaign") give the agent clear triggers. It does not explicitly name a sibling to use instead when a single link is already known (get_link) or when an unfiltered listing is wanted (list_links), so routing guidance is strong but not exhaustive.

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