ck_list_subscribers

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

With no annotations, the description carries full burden for behavioral disclosure. It only states 'list all subscribers' without mentioning that it requires authentication via api_secret, whether it is a read-only operation, supports pagination (implied by the page parameter), or any rate limits. The description fails to set accurate expectations.

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, concise sentence. It is front-loaded and directly states the core action. However, it is perhaps too brief, omitting necessary details for effective use.

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 has 6 parameters (including filtering and pagination), no output schema, and no annotations, the description is incomplete. It fails to explain pagination, sorting, filtering by date range, and the authentication requirement. Users cannot effectively use the tool from this description alone.

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 50%, but the description adds no parameter semantics. It does not explain the purpose of 'page', 'to', 'sort_field', or the expected format of 'from' beyond what the schema provides. The description should compensate for the missing parameter descriptions but does not.

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 the verb 'list' and the resource 'subscribers in a ConvertKit account', making the purpose clear. It distinguishes from sibling tools like ck_add_subscriber, ck_list_forms, etc., which operate on different entities or actions. However, the phrase 'all subscribers' is ambiguous given the pagination parameter (page) suggests not all may be returned in a single call.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., valid API secret), filtering, or that it paginates results. The description lacks any context for appropriate use.

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