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

Annotations already signal the tool is not read-only, not destructive, and idempotent. The description adds a useful behavioral detail—error on plan-limit exceedance—and platform/type validation rules. However, it does not describe the success return format or what happens when duplicate items are added, though the idempotentHint does partially mitigate duplication concerns.

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 only three short sentences, each adding value: the primary action, the accepted shape, and the most relevant failure mode. It is front-loaded with the verb and subject, and contains no filler or tautological content.

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 is a simple add operation with a small schema, and annotations cover mutability and idempotency. The description supplies the core semantics and the plan-limit error. Yet with no output schema, the description would be stronger if it mentioned success information (e.g., what is returned on a successful add, whether item creation is reflected immediately), so the agent can confirm the call succeeded.

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 low (40%), and the description helps by surfacing the key enum values and platform/type constraints in a compact form. However, it mostly restates what the nested schema already provides and omits any explanation of _isTrial, _requestId, and _trialToken, which are not otherwise described. Still, the required items parameter gets sufficient treatment.

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 begins with a clear verb and resource: 'Add keywords/users to track.' It expands on scope by listing the exact item types and platforms, making the operation unambiguous. The name and description clearly distinguish it from getTrackedItems and removeTrackedItems, which are the only close 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?

The description implies the intended use by stating it adds items, and it gives explicit platform restrictions: 'Subreddit is Reddit-only, hashtag is TikTok-only.' It does not explicitly say 'use getTrackedItems to view current items' or 'use removeTrackedItems to delete', but these are clear from naming and context. Slight gap is the lack of when-not-to-use or alternatives guidance beyond naming.

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