search_logs

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

With readOnlyHint=true and destructiveHint=false already covering safety, the description adds valuable behavior: it returns trimmed entries, includes a '_why' explanation of blocks, and discloses that some filters are applied server-side while user/src_ip are matched locally for other log types. This goes beyond the annotations without contradicting them.

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?

Two sentences carry a lot of information with no filler: the read-only marker, log types, filter capability, time window, return format, and a key behavioral caveat. The most important scoping information is front-loaded and every clause earns its place.

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 tool with 17 parameters and no output schema, the description covers the essential purpose, return shape, and a critical behavioral distinction (server-side vs local filtering). It does not fully describe every return field or edge-case behavior, but combined with the rich schema, this is sufficient for an agent to invoke it 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?

The input schema has 100% parameter coverage with helpful descriptions, enums, and defaults, so the baseline is 3. The description adds extra semantic value by clarifying how structured filters behave depending on log type (server-side vs local matching for user and src_ip), which is not captured in the schema.

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 ('Searches') and resource ('logs stored on Panorama'), enumerates ten log types, and mentions structured filters, time windows, and a '_why' explanation. It is clear and specific, but it does not explicitly differentiate itself from sibling tools like get_traffic_logs or get_threat_logs, so it does not earn a 5.

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 implies usage context: it is for searching Panorama logs across many types with structured filters and time windows. It also notes which filters are server-side vs local, which is useful operational guidance, but it never explicitly says when to prefer search_logs over the dedicated get_*_logs siblings.

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