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

Annotations are all false, providing no safety or side-effect hints, so the description carries the full burden. It reveals rate limiting ('Rate-limited to 5 per identifier per day'), the anonymous claim_token flow, that feedback is free and doesn't count against quota, and that the team reads digests daily — all valuable behavioral context beyond the schema.

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 substantial but every sentence serves a purpose: what it does, when to use, when not to use, how to format feedback, the claim_token flow, rate limit, and cost. It is front-loaded with the core verb and resource, then layers details logically. No fluff or repetition of schema field definitions.

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?

With no output schema and a nested context object, the description must clarify return behavior and usage boundaries. It explains that anonymous filing returns a claim_token and that passing it later returns status/resolution. It covers prerequisites (no account needed), limitations (rate limit), and scope (only this connection's tools). This is complete for the tool's purpose.

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 100%, but the description adds meaning beyond the schema: it explains how to use claim_token for later lookup ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), and constrains message content ('describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). The type enum is also mapped to concrete scenarios.

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+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx by focusing on reporting issues about the Pipeworx connection's own tools.

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 explicit when-to-use guidance for each feedback category and an unequivocal exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' Also gives a decision heuristic for identifying Pipeworx tools ('Pipeworx tool names are the ones this connection lists').

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