Search Lists

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

Annotations already declare read-only and idempotent, and the description adds real context beyond them: an API key requirement, one request per call at ~1 unit cost with a per-result cost estimate, and the non-obvious fact that a short page is not necessarily the last one. That pagination caveat is exactly the kind of behavioral detail annotations cannot convey.

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 purpose, then chaining, then safety/cost, then pagination — a sensible order with no filler. The final sentence partially restates the cursor parameter description, a minor redundancy.

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 shape need not be re-explained, and the description still covers auth, cost, page-size caveats, and continuation, which are the things an agent must know to invoke it correctly. Nothing material is missing for a cursor-paginated search tool.

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 all three parameters (including the responseFormat enum and cursor provenance) are already documented in structured form. The description reinforces cursor handling but adds no syntax or constraint beyond what the schema states, so baseline 3 applies.

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 ("Search X Lists by keyword") plus the exact scope ("fetch one page of matching Lists"), which distinguishes it from the ID-based siblings like tweetapi_list_details and tweetapi_list_tweets. An agent can select it without opening the 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?

Gives explicit downstream routing ("Use the List IDs with tweetapi_list_tweets or tweetapi_list_members") and precise pagination instructions for when to re-call with a cursor. It does not explicitly say when to prefer this over other search entry points such as tweetapi_search, so it falls short of full alternative coverage.

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