semantic_search

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

No annotations are provided, so the description carries the transparency burden. It discloses that search is semantic and embedding-based, not exact-name matching, and gives realistic conceptual examples. For a non-mutating search tool this is sufficient, though it does not describe result ordering or output details.

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 description is front-loaded with the core purpose, then immediately gives usage guidance and illustrative examples. Both sentences earn their place, and the examples are varied enough to be useful without being bloated.

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?

Given no output schema and no annotations, the description covers purpose, when to use, query style, and filters via the schema. It is complete enough for an agent to construct a correct request, though it could briefly state what kind of results the tool returns.

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 optional filters are already well documented. The description adds value by clarifying what kinds of query phrasing are acceptable, including cross-framework conceptual equivalents like 'react useEffect on mount equivalent,' which goes beyond the schema's brief examples.

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 ('Search Apple Developer Documentation') and clearly distinguishes the mode: natural language intent, behavioral description, or UI concept rather than exact symbol lookup. This separates it from siblings like search_symbols without ambiguity.

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?

The description explicitly says to use this tool when you do not know the exact Apple API symbol name or need conceptual/layout queries, with concrete examples. It implies the when-not case but does not explicitly name search_symbols or state 'use that instead for exact matches.'

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