x_api_delete_activity_subscriptions_by_ids

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

With no annotations provided, the description carries full burden and excels. It discloses risk ('mutating, high-risk'), required permissions ('bearer token'), environment-selection behavior (scopeTenantId plus scopeUserId/scopeAccountId, credentialKey), common failure conditions, and safety warnings. This goes far beyond minimal disclosure.

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 organized into labeled sections (Use when, Risk, Required permissions, etc.), making it easy to scan. It is slightly verbose with some repetition (the purpose line reappears in 'Use when'), but every section contributes distinct operational detail. This is efficient for a complex tool.

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?

Despite 7 parameters, no annotations, and no output schema, the description covers all key aspects: purpose, usage boundaries, risk, permissions, environment behavior, param formats, expected response shape, failure conditions, recommended tools, safety warnings, and an example. This is comprehensive for a mutating API 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 0%, so the description must add parameter meaning. It explains ids as 'query, array, required' and clarifies the role of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in environment selection. However, it does not elaborate on authorizationKey or preferredAuthType, leaving some parameters to rely on schema constraints alone.

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 'Delete X activity subscriptions by IDs', which clearly states the action (delete), the resource (X activity subscriptions), and the scope (by IDs, distinguishing it from singular deletion tools like x_api_delete_activity_subscription). This is a specific verb+resource+differentiator.

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 includes explicit 'Use when' and 'Do not use when' sections. The 'Do not use when' section mentions preferring x_schema_discovery or x_query_suggestion for exploration and notes when auth/configuration tools are needed. However, the 'Use when' section simply restates the purpose, and it does not explicitly contrast with sibling deletion tools (e.g., singular vs. plural). This is clear context with some alternatives, but not exhaustive.

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