Skip to main content
Glama

rate_tool

Destructive

Give honest usage feedback on an IA-QA MCP tool. Give a score (1-5) and a comment. Rate low (1-2) if the tool was wrong, irrelevant, or a poor fit; rate high (4-5) only if it genuinely solved your need. Maintainers read ratings, one vote per agent and tool a month: comments and per-tool scores are not published, only the overall average and vote count. Comments are screened: one carrying a credential is not stored, personal data becomes placeholders — describe what happened, not what a model should do. Skip routine successes: signal, not praise. Example: rate_tool({ tool_name: "format_json", score: 2, comment: "Tried to pretty-print a JSON5 file, it rejected trailing commas — not usable for my case." })

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "score": 4,
      "comment": "Formatted a 2 MB payload correctly.",
      "tool_name": "format_json"
    },
    "name": "rate_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
scoreYesRating from 1 (poor) to 5 (excellent)
commentNoStrongly encouraged — explain what you were trying to do and whether the tool got you there. Be specific about what was missing, wrong, or a poor fit. This is the most valuable part of the rating. Up to 2000 chars are stored; go over and the response says so (truncated: true) — send the remainder as a second call rather than assuming it landed.
tool_nameYesName of the MCP tool to rate (e.g. "format_json", "shield_analyze")

Output Schema

NameRequiredDescriptionDefault
okNo
scoreNo
commentNo
messageNo
rated_atNo
tool_nameNo
truncatedNo
stored_charsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / examples
      Added value: +[
      +  {
      +    "comment": "Formatted a 2 MB payload correctly.",
      +    "score": 4,
      +    "tool_name": "format_json"
      +  }
      +]
  2. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Rich disclosure that annotations cannot carry: one vote per agent and tool a month, comments and per-tool scores unpublished (only aggregate average and count), and a moderation pipeline where credentialed comments are dropped and personal data is placeholderized. It does not contradict destructiveHint=true, but it never states whether the vote is final or can be revised/deleted, which is the one behavior an agent submitting an irreversible write would want confirmed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action, then rubric, then disclosure, then moderation policy, then a worked example — a sensible funnel with no filler sentences. It is on the long side for a three-parameter tool, and the example largely restates the rubric plus the schema's own example, but nothing is genuinely wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need not be explained, and the description covers the non-obvious parts an agent actually needs: rubric, audience, privacy/publication rules, screening rules, and rate limiting. The remaining gap is modest but real — nothing tells the agent whether a submitted vote is permanent or overwritable, which matters for a tool flagged destructive and non-idempotent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so name/score/comment are already documented, making 3 the baseline. The description does add real meaning above the schema's bare '1 (poor) to 5 (excellent)' by anchoring what 1-2 versus 4-5 looks like and by constraining comment content ('describe what happened, not what a model should do'), but it adds nothing new about tool_name or the 2000-char truncation behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'Give honest usage feedback on an IA-QA MCP tool', then names the two things that must be produced (a score and a comment). 'Rate' + 'IA-QA MCP tool' is unmistakable and cannot be confused with any sibling (bias_detect, shield_analyze, etc. all analyze content; this one submits meta-feedback).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Supplies an explicit rubric: low (1-2) for wrong/irrelevant/poor fit, high (4-5) ONLY if it genuinely solved the need, plus an explicit exclusion — 'Skip routine successes: signal, not praise.' That is a when-to-use, when-not-to-use, and a calibration anchor in one place, leaving nothing to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.