Search IOCs

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

With readOnlyHint=true and destructiveHint=false annotations already establishing safety, the description adds valuable behavioral context: the has_more semantics, the limit cap, and the critical note that offset isn't honored (so paging won't work). This functional caveat is genuinely useful behavioral disclosure beyond what annotations provide.

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?

Compact two-sentence description, front-loaded with purpose. The parenthetical about the offset limitation is efficiently integrated rather than a separate paragraph. Slightly dense but every sentence 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?

Given an output schema is present and a 3-param tool with 100% schema coverage, the description covers purpose, filtering modes, limit behavior, and the unusual offset caveat. The sibling landscape has many IOC-adjacent tools, so explicit guidance on when to use this vs search_xscan_indicators would push it to 5, but for its complexity level the completion is strong.

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 the note on narrowing with more specific substrings instead of paging, which adds a bit of guidance, but the description largely restates what schema already documents (type/value/limit defaults). No new semantic detail beyond defaults and pagination caveat.

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?

Clear verb+resource: 'Search indicators of compromise' with specific types listed (IPs, domains, hashes, URLs). Distinguishes from siblings like search_vulnerabilities and search_threats by naming the IOC domain, though it doesn't explicitly name sibling alternatives.

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?

States filtering modes (value substring and/or category) and the limit behavior with the has_more flag. However, it doesn't explicitly say when to choose this over search_xscan_indicators or get_ioc_intelligence, which are nearby siblings operating on IOCs. The note about offset not being honored provides usage constraint context.

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