search_social

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

No annotations are present, so the description carries the full burden of behavioral disclosure. The description only says it searches 'across' multiple providers, but does not disclose that results are aggregated/merged from multiple sources, how provider failures are handled, whether results are deduplicated, or any rate limits or authentication requirements. The behavior around num_results per provider vs. max_total_results is also not clarified.

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 a single, front-loaded sentence with no filler. It efficiently communicates the tool's core function and scope, and every word contributes to purpose clarity.

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 multi-provider aggregation complexitycasting, the absence of annotations, and lack of an output schema, the description is insufficiently complete. It omits critical operational context such as result merging behavior, why there are two limit parameters, error handling across providers, and what the returned data structure looks like. An agent would likely need additional probing to invoke it correctly in complex scenarios.

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 baseline is 3. The description does not add meaningful parameter-level information beyond the schema; it mentions the platforms but not query syntax, result formatting, or how the two result-limit parameters interact. Thus it neither improves nor harms parameter understanding.

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 ('Search') and resource ('social media posts and community discussions'), and explicitly names the platforms covered (Bluesky, Mastodon, Lemmy, Lobsters). This clearly distinguishes it from siblings like search_web, search_news, and search_images, which target different content types.

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 (when searching social media or community discussions) but provides no explicit guidance on when not to use it or which sibling alternatives to prefer. It does not mention overlapping tools like search_news or search_web, leaving the selection decision to the agent's inference.

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