search_across_sites

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

No annotations are provided, so the description carries full burden. It discloses that search is across all sites and returns site context, but lacks details on performance, pagination, or any non-obvious behaviors (e.g., rate limits). Transparency is adequate but not comprehensive.

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 extremely concise with a clear structure: brief intro, search scope, use case, and explicitly labeled Args/Returns sections. Every sentence is purposeful and no unnecessary words.

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 the tool's moderate complexity (2 params, output schema exists), the description covers the search scope, query types, and site context in returns. It does not elaborate on output schema but that is acceptable since an output schema is present. Minor gap: no mention of result count or limitations.

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 0%, so the description must compensate. It fully explains both parameters: 'query' (supported formats) and 'search_type' (valid values with default). This adds crucial semantic meaning beyond the schema's type-only definitions.

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 clearly states the tool's purpose: searching for resources (devices, clients, networks) across all managed sites. It specifies the resource types and highlights usefulness in multi-site deployments, distinguishing it from single-site or inventory tools among siblings.

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 provides context ('useful for locating resources in multi-site deployments') but does not explicitly state when not to use this tool or mention alternatives. Clear guidance is given on the scope, but exclusions are absent.

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