list_carrier_subscribers

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

With no annotations, the description carries the full behavioral burden. It discloses pagination behavior ('Cursor-paginated by the API; every page is drained'), visibility scope ('visible to the authenticated ISP key'), and a notable testing caveat ('hermetic/spec-conformance tested only'). It also confirms the return shape ('complete list is returned under subscribers'). While it doesn't cover permissions or rate limits, the disclosed details are substantial and useful.

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 information-dense with each sentence earning its place: function, testing caveat with pagination, and parameter semantics. A slight redundancy exists ('Not testable...' and 'the Carrier Fabric is not deployed here') and the second sentence is long, but overall it is structured and efficient.

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 output schema exists and all parameters are described, the core calling requirements are covered. The testability caveat adds important context. The main gap is the lack of guidance on when to use this tool versus related carrier subscriber tools, which would make the context fully complete.

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 0%, so the description must compensate fully. It does: each parameter is explicitly explained with acceptable values, including the sort options (createdAt/-createdAt/name/-name/subscriberNumber/-subscriberNumber) and the purpose of key_label. This exceeds what the bare schema provides and gives an agent enough to use the parameters 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 opens with a specific verb and resource: 'List Carrier / ISP Fabric subscribers visible to the authenticated ISP key.' This clearly identifies what the tool does and its scope, distinguishing it from related tools like get_carrier_subscriber (single item) and list_carrier_service_plans (different resource).

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 does not state when to use this tool versus alternatives or provide exclusions. It mentions the testability limitation and pagination behavior, but offers no guidance on selecting this list tool over the many sibling carrier tools. Context is implied only by the tool's name and general list purpose.

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