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

The description adds valuable behavioral context beyond the annotations: it discloses the rate limit (5 per identifier per day), that it does not count against tool-call quota, that filing without an account returns a claim_token for later follow-up, and that the team reads digests daily. This goes well beyond the sparse annotations (which only indicate non-read-only, non-idempotent, non-destructive) and paints a clear picture of the tool's side effects and constraints.

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?

While the description is long, every sentence earns its place: it establishes purpose, gives use cases, excludes non-Pipeworx tools, explains token mechanics, notes rate limits, and clarifies cost/quota implications. The structure is front-loaded with the main action and progressively adds operational details without redundancy.

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 fully specified despite having no output schema: the description explains both filing feedback and how to retrieve the resolution via claim_token. It covers prerequisites (identifying Pipeworx tools, not pasting end-user prompts), behavioral limits (rate limiting, quota exemption), and the human workflow (daily digests, roadmap impact). For a feedback tool with this complexity, nothing critical is omitted.

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 provides complete descriptions for all four parameters (100% coverage), so the description carries less burden. However, it adds meaningful operational semantics for the claim_token parameter, explaining that it should be passed alone to read previous feedback status, and it clarifies that context is optional structured data. This slightly elevates it above the baseline 3.

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 the specific action 'Tell the Pipeworx team something is broken, missing, or needs to exist,' making the tool's purpose immediately clear. It distinguishes itself from sibling research/entity tools by explicitly focusing on feedback about Pipeworx tools themselves, and it defines the feedback categories (bug, feature, data_gap, praise) with concrete examples.

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 gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: tools from other MCP servers should not be reported here, and explains how to identify Pipeworx tools. The claim_token usage is also explicitly instructed.

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