find_resource

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

Even with annotations (readOnlyHint, idempotentHint, destructiveHint) already establishing a safe read-only profile, the description adds valuable behavioral detail: it never silently picks a match when multiple records exist, details exact resolution order, explains ambiguity handling, and describes pagination semantics with next_cursor. This goes well beyond annotation hints and fully discloses the tool's search behavior.

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 purpose, then organized into a clear 'Args' list, with each parameter explained in a tight sentence. No fluff or repetition beyond what is necessary for context. At ~150 words for a 4-parameter tool with complex matching semantics, it is appropriately sized and well-stuctured.

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?

Covers all key aspects of the tool: supported object types, matching rules, ambiguity behavior, pagination (cursor, limit, defaults), and explicit alternatives for uncovered object types. Given the output schema exists, return-value details are not required. For a search/resolution tool of this complexity, the description is complete and self-sufficient.

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 input schema already documents all four parameters thoroughly. The description's param details largely mirror the schema text (e.g., 'Exact ID match wins first, then exact name...' and 'Opaque pagination token'). Thus it adds no new meaning beyond the schema; it simply repeats it in prose, meeting the baseline of 3 but not exceeding it.

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 opens with a specific verb and resource: 'Resolve common Prisma SD-WAN objects by human name or exact ID.' It then enumerates the exact object families covered and explicitly distinguishes itself from sibling tools (find_site/find_element) by stating they are for sites/ION elements while this tool is not. This fully clarifies purpose and differentiation.

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 explicit usage context: which object types to use it for, and a direct exclusion: 'Use find_site/find_element instead for sites or ION elements — this tool does not cover those.' It also describes the prioritization logic for name matching (exact ID, exact name, substring) and warns about ambiguity, giving the agent clear behavioral guidance for when to call and what to expect.

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