Search Framework Symbols

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: results omit summaries, nested symbols count toward the limit, and namePattern matching is case-insensitive. It does not discuss pagination or failure cases, but for a read-only index search this is solid.

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 compact and front-loaded: it starts with what the tool returns, then parameter clarifications, then the follow-up tool. Every sentence carries information, and semicolons keep it dense without 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?

Given five parameters, no output schema, and only a readOnly annotation, the description covers the essential return shape (name, link, kind, no summaries) and the core filtering behavior. It stops short of specifying pagination or full output structure, but it provides enough for an agent to call the tool 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?

Schema description coverage is 100%, so the schema already documents all five parameters with examples. The description adds the useful detail that framework is the last segment of the documentation link, but much of its parameter text repeats schema content such as the limit including nested symbols and namePattern case-insensitivity. Baseline 3 is appropriate when the schema does the heavy lifting.

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 resource and scope: symbols from one framework's navigator index, with name, link, and kind but no summaries. It distinguishes this from full-content retrieval by naming get_apple_doc_content, so an agent can tell it apart from siblings such as search_apple_docs.

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?

Provides clear context: use a framework identifier obtained from list_technologies, filter by symbolType, and use namePattern for wildcard matching. It also names get_apple_doc_content as the next step for reading a symbol. However, it does not explicitly say when to prefer this tool over search_apple_docs or other search siblings.

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