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

The description adds several behaviors beyond the annotations: local validation prevents malformed calls from costing credits, responses report endpoint price and metered rules, and idempotencyKey enables retry-safe behavior with 0-credit replays. None of these contradict the annotations, and they substantially enrich the agent's understanding of call semantics.

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 dense but well-organized: it opens with purpose, then covers HTTP method conventions, alternatives, authentication, validation, pricing, and retry semantics in a logical order. Each sentence conveys distinctive information needed for a generic 572-endpoint gateway, with no 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?

For a tool with no output schema and enormous endpoint variety, the description covers every essential operational aspect: platform/resource identification, GET/POST handling, body/params mapping, required API key, free local validation, cost reporting, idempotency, and routing to the correct sibling tool. It appropriately defers exhaustive endpoint details to list_endpoints.

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 meaningful interaction-level semantics: it clearly distinguishes when to use `params` versus `body`, gives concrete examples for each, and explains the role of idempotencyKey beyond the schema's field description. This exceeds baseline by helping the agent assemble requests correctly.

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: making an API request to any of the 572 SocialCrawl endpoints, and lists the broad data categories and platforms it covers. It distinguishes itself from the socialcrawl_web sibling by explicitly excluding web scraping/crawling/browser automation use cases.

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 clear usage guidance: most endpoints are GET with query params in `params`, while batch endpoints are POST with body in `body`. It explicitly directs users to the socialcrawl_web tool for web scraping alternatives and references socialcrawl_list_endpoints to determine where parameters belong.

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