x_api_get_users_muting

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

Despite no annotations, the description extensively discloses permissions (OAuth scopes), auth-resolution behavior, expected response shape, common failures, and safety warnings. It clearly states 'Risk: read-only' and warns about sensitive data, exceeding baseline transparency. However, it doesn't explain the payload contents or pagination details, so a 4 is appropriate.

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 well-structured with clear labeled sections (Risk, Required permissions, Expected response, etc.) and an example. The only waste is the redundant 'Use when: Get muting' line, but overall it's organized and scannable.

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?

The tool has 9 parameters, no annotations, and no output schema, yet the description omits the core semantics: what exactly is being retrieved and what fields the response contains. It provides operational details like failures and auth, but without a clear definition of 'muting', the agent cannot determine if this tool fits the user's request.

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 0%, and the description only partially compensates. It lists id, max_results, and pagination_token with minimal types, and explains the scopeTenantId/scopeUserId/scopeAccountId/credentialKey interplay in prose. However, it omits authorizationKey and preferredAuthType, and fails to describe what 'id' represents (the user whose muting list is being fetched).

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 'Get muting', which merely restates the tool name without specifying the resource or action clearly. It does not mention that this retrieves a list of users muted by the authenticated user, making it indistinguishable from sibling tools like x_api_get_users_blocking.

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?

'Use when: Get muting' is tautological and provides no decision context. The 'Do not use when' clause only covers exploration and prerequisite scenarios, not when to prefer alternative muting-related tools. It offers no guidance on when this tool is the right choice versus x_api_mute_user or x_api_unmute_user.

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