Social Get Comments

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

No annotations are present, so the description carries the full burden, and it delivers: it discloses pagination differences per source, that offset is ignored on profile, that replies are included free on profile, and the live-feed shift caveat. It also flags the request cost of include_replies. This is comprehensive behavioral 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 summary sentence is front-loaded and each subsequent section earns its place. The dash/bullet layout makes the source-specific behavior scannable rather than a dense wall of text.

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's complexity (three sources with divergent pagination) and no annotations, the description covers all known call-time behaviors: what is returned, pagination, nesting model, cost, and stability caveat. The output schema exists, so return values need no description. Nothing essential is missing.

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?

The input schema already covers all parameters, so baseline is 3, but description compensates far beyond: it explains the meaning of limit/offset for project/studio, explains that page is profile-only with 30 per page and offset ignored, and quantifies the include_replies request cost. This materially improves an agent's ability to set 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?

Opens with a precise verb and target ('Page through the comments on a project, a studio, or a user's profile'), and then explicitly narrows scope by saying only top-level comments are listed, with replies handled separately. This distinguishes it from social_get_comment_replies and posting tools without needing to open schemas.

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?

Provides detailed when-to-use guidance: source-specific pagination choices, when include_replies is worth its cost, and when it is irrelevant. It gives clear context though it never names the sibling tool (social_get_comment_replies) as the explicit alternative for reply-only fetches, so not quite a 5.

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