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

The annotations already indicate a non-read-only, open-world, non-idempotent but non-destructive operation, and the description adds useful behavioral details beyond them. It discloses that the investigation is async, returns an investigationId immediately, requires operator authorization, and degrades gracefully when unprovisioned. It does not provide rate limits or a fuller explanation of what 'degrades to info' entails, but it does not contradict the annotations.

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 front-loaded with the core action and stays tightly structured across three sentences. It covers purpose, deployment constraints, and the immediate return/polling behavior without wasted wording.

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 an async start tool with no output schema, the description is nearly complete: it explains the immediate return value and points to the status tool for polling. The main missing context is a clearer statement of what the deep-infrastructure investigation covers and how it differs from the other investigation starters. The operator-authorization and degradation notes make it usable.

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 100%, so the query parameter is already documented in detail. The description adds examples by saying the query can be a domain, IP, or org, but this does not materially extend the schema and is slightly narrower than the schema's mention of email address and username. With full schema coverage, the baseline score of 3 is appropriate.

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 and resource: starting an async deep-infrastructure OSINT investigation for a query. It also scopes acceptable subjects to domain, IP, or org and names the status tool for polling. It is clear, but it does not explicitly distinguish this tool from sibling investigation starters such as osint_investigate_domain_start or osint_investigate_supply_chain_start.

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 gives meaningful context: operator-deploy only, targets must be operator-authorized on the recon watchlist, and the tool degrades to info when unprovisioned. It also tells the agent to poll results with osint_investigation_status. It does not explain when to choose this starter over the other OSINT investigation starters, so explicit exclusions and alternatives are missing.

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