Cosmos

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior on top: per-resource credit cost, that failures are free, that the response reports what was charged and what remains, that list resources return an opaque `cursor` to be passed back unchanged, and that max_age_days trades freshness for zero credits. These are exactly the operational facts an agent needs before spending credits.

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 the calling convention, then a scannable bulleted resource list with credit costs. Every sentence carries actionable information (credits, cursor, caching) and there is 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?

With 7 parameters, a nested `params` object, and no output schema, the description does the important work: it explains what a result reports (credits charged, credits remaining) and the cursor-paging contract. It stops short of describing the shape of the returned Cosmos objects and defers per-resource optional parameters to `describe` rather than listing them as claimed.

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 earns an extra point by compactly binding each parameter to its resource (url for collection/collection.posts/post, handle for the profile family, query for search) and by explaining the `params` escape hatch. It slightly over-promises, however: it says optional parameters of each resource are in the tool description, but only max_age_days is actually listed there.

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 names a concrete verb and resource set ("Data from Cosmos: profiles, posts and videos, collections") and then enumerates every supported resource with the argument each takes (collection(url), profile(handle), search(query)). An agent can tell instantly that this is the Cosmos platform extractor rather than the generic get_profile/get_post siblings.

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?

It gives a clear calling pattern ("Pick a resource, then pass its parameters as top-level arguments (extras in params)") and explains the two alternative modes: pass max_age_days for a free cached copy, or pay credits for fresh data. It also routes to `describe` for types and allowed values. What's missing is explicit guidance on when to choose cosmos over the generic get_profile/get_post/search siblings.

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