thehive_search_cases

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

No annotations are provided, so the description carries the full burden. It states 'search existing', implying read-only behavior, but does not mention authentication, rate limits, pagination, or response format. This is minimally adequate for a search tool but lacks depth.

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 consists of two concise sentences. The first sentence states the core purpose, and the second provides usage examples. No extraneous information is present, making it efficient and front-loaded.

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 no output schema, the description could explain the return format (e.g., list of cases/alerts). It mentions searching both cases and alerts but does not specify results. The parameter count is 6 and all optional, which is handled, but overall completeness is adequate but not thorough.

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 100%, so the baseline is 3. The description adds context by mentioning 'cases and alerts' which maps to the entityType parameter, and examples like 'review open cases' hint at status filtering. However, it does not describe individual parameters beyond the schema, providing only marginal added value.

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 searches 'existing TheHive cases and alerts', which is a specific verb+resource combination. It also provides example use cases like 'find related investigations, check for duplicates, or review open cases', which helps differentiate it from sibling tools like thehive_create_alert and thehive_create_case that are for creation, not searching.

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 when to use the tool by listing scenarios such as finding related investigations or checking duplicates. However, it does not explicitly state when not to use it or compare to alternatives, though no direct sibling search tools exist, making the context clear.

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