Use when: a solution is factually wrong, malicious, contains PII/secrets, or is spam. Returns: report count; removal after 3 reports. Do not use when: the fix did not work in your specific case or you merely disagree with the approach.
| Name | Required | Description | Default |
|---|---|---|---|
| solution_id | Yes | ID of the solution to report |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that reporting increments a count and that removal occurs after 3 reports, along with the return value 'report count.' This goes beyond the annotations, which only indicate read/write/destructive hints. It does not mention other potential side effects, but the provided context is sufficient for a simple reporting action.
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 three concise sentences, each serving a clear purpose: usage criteria, output/behavior, and exclusions. It is front-loaded with the most important information and contains no filler or 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?
For a tool with a single parameter, no output schema, and present annotations, the description covers purpose, usage boundaries, output, and the threshold effect. It clearly states what the agent will receive ('report count') and the consequence of repeated reporting. It is complete enough for an agent to use appropriately.
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 single parameter solution_id is already fully described in the schema (100% coverage). The tool description does not add additional parameter-specific semantics beyond what the schema provides, so it meets the baseline but does not exceed it.
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 explicitly states the tool's purpose: reporting a solution when it is factually wrong, malicious, contains PII/secrets, or is spam. This is a specific verb+resource combination that clearly distinguishes it from sibling tools like search_solutions or submit_solution.
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 provides explicit 'Use when' and 'Do not use when' conditions. It tells the agent exactly when to invoke the tool and, importantly, when not to (e.g., when a fix didn't work or merely disagreeing), which is clear actionable guidance without requiring inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a distinct purpose: adding addenda vs. editing core solutions vs. submitting new solutions vs. filing issues vs. searching, etc. There is no overlap; the descriptions clearly differentiate when to use each tool.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_addendum, search_solutions). The verbs are descriptive and the structure is uniform, making it predictable for an agent.
With 9 tools, the server is well-scoped for a solution and issue management domain. Each tool serves a needed function without redundancy or bloat, covering the core workflows adequately.
The tool surface covers creation, reading, updating (via suggest_edit and add_addendum), and a reporting mechanism for problematic content. File submission and issue resolution are included, but there is no explicit tool for deletion or archival, which is a minor gap.