search_resources

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond the annotations: it returns declarations or references with source locations, excludes runtime guarantees, and warns about incomplete older snapshots. This is useful behavioral disclosure without contradicting annotations.

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 dense, purposeful sentences. The first sentence states the action and scope immediately; the second and third add necessary caveats about runtime availability and historical coverage. No filler or repetition of schema details.

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 six parameters and no output schema, the description explains what results contain, what they do not prove, and when coverage may be missing. Pagination is handled in the offset parameter description, so the overall package is nearly complete, though the description itself could have briefly mentioned offset pagination for extra robustness.

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 input schema already provides meaningful descriptions for query, channel, version, and offset, covering 67% of parameters. The description's enumeration of resource kinds mirrors the kind enum and adds little parameter-level meaning beyond that. It does not compensate for the missing descriptions of kind and limit, but the schema gives sufficient guidance overall.

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: searching Blizzard source resource names (symbol, template, mixin, frame, CVar, atlas). It also distinguishes itself from sibling runtime/API lookup tools by explicitly saying it returns source declarations/references and does not prove runtime availability.

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?

Clearly signals when not to use the tool: it does not prove runtime availability or a callable API contract, and older snapshots may lack resource coverage. It does not explicitly name alternatives like lookup_runtime_resource or search_api, but the when-not conditions are clear enough to route an agent.

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