user_search

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

With no annotations provided, the description carries the full burden and does well. It discloses polling until completion, response truncation with the truncated: true indicator, and the results_pending status meaning results are still being written. These are meaningful behavioral traits beyond what the schema conveys.

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 four sentences, each serving a purpose: stating the action, describing the polling behavior, noting truncation, and explaining results_pending. It is somewhat lengthy but well-structured and front-loaded with the core action.

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 the tool's moderate complexity (async search, possible truncation, pending status) and the absence of annotations and output schema, the description is quite complete. It explains key behaviors and points to sibling tools for resolution of special states, leaving no major gaps for an agent to infer.

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 descriptions cover all four parameters (100% coverage), so the baseline is 3. The description does not add parameter-level detail beyond what the schema already provides; it only references social media platform and the overall action.

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?

Description opens with 'Create a user profile search on a social media platform', a specific verb+resource statement. It clarifies the polling and result-return behavior, and contrasts with sibling tools like get_user_search and get_user_search_posts which are referenced for follow-up actions.

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?

Provides explicit guidance for two edge cases: truncated responses should use get_user_search_posts, and results_pending status should be followed up with get_user_search. This gives clear alternatives for specific outcomes, though it does not broadly contrast with other search initiation tools like keyword_search.

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