fofa_search

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that this reads indexed data rather than scanning or probing targets, and reveals the pagination contract (has_more / next_token). It says nothing about authentication requirements, rate limits, or what the 'confirm' and 'task_id' parameters actually do, which leaves gaps for a tool with an undocumented 'confirm' flag.

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?

Front-loaded with the core action, then a sequence of short routing sentences that each carry distinct decision value. The only mild cost is that the routing list is long relative to the tool's single required parameter, but no sentence is pure filler.

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?

An output schema exists, so return-value documentation is not required, yet the description still usefully surfaces the has_more/next_token continuation contract. The gap is parameter completeness: with 0% schema coverage on 8 parameters, an agent cannot tell what confirm, task_id, format, or fields control, so the definition is not fully 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 0% across 8 parameters, and the description clarifies only the meaning of 'query' (a FOFA DSL expression). Page, size, fields, format, confirm, task_id, and request_id are left entirely undocumented in both the schema and the description, including the potentially consequential 'confirm' boolean.

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?

States a specific verb and resource ('Run one page of a complete FOFA DSL query') and implicitly scopes it against siblings by naming the conditions under which each alternative applies. An agent can distinguish it from fofa_search_structured and fofa_search_next without opening any schema.

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?

Explicit routing: use this when a DSL query already exists, use fofa_search_structured for ordinary domain/IP/port conditions, chain to fofa_search_next when has_more=true and next_token is present, and reserve fofa_stats and fofa_host for their specific cases. Both when-to-use and when-not-to-use are covered with named alternatives.

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