Skip to main content
Glama

report

PREFERRED way to give feedback, using the top-level report_token from search_tools/get_tool/compare_tools (covers the first 10 results, valid 30 days). Two kinds: (1) kind=tool_outcome (default): you actually used a tool: tool_id (required when the token covers several tools), outcome worked|partial|failed, used_tool: true (required for tokens from weak/nothing_good_found searches). (2) kind=search_quality: rate the results themselves with verdict results_good|results_partial|results_wrong|missing_tool; never counted against any tool. Note max 300 chars. Reuse your contributor_key.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "report_token": "<report_token>"
    },
    "name": "report"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNo
noteNo
stageNooptional, self-declared
clientNooptional, e.g. claude-code, cursor, my-agent
outcomeNo
tool_idNorequired for tool_outcome when the token covers more than one tool; never defaulted
verdictNo
used_toolNotrue = you actually called/used this tool
agent_typeNooptional, self-declared
report_tokenYes
expected_toolNosearch_quality: what you expected to find (name or URL)
contributor_keyNoYour contributor_key from your FIRST write (format ck_...). Reuse it on every write; omit only on your very first write. We never mint a second key when you send one.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already mark this as a non-read-only, non-destructive, non-idempotent, closed-world write, so the safety profile is covered. The description adds genuinely non-structural context: the token's 30-day validity, that it covers the first 10 results, that notes cap at 300 characters, and that search_quality verdicts are never counted against a tool. It does not explain what happens on an expired/consumed token or what a repeat submission does, which matters given idempotentHint=false.

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

Conciseness5/5

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

Front-loads the value proposition ('PREFERRED way to give feedback') and the token source, then splits the two modes into numbered branches, keeping every sentence load-bearing. The only waste is restating the 300-character limit already encoded in the schema.

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?

For a 12-parameter write tool with no output schema, the description covers token provenance, mode selection, conditional requirements and the contributor_key lifecycle — most of what an agent needs to invoke it correctly. What it omits is failure/expiry behavior and any differentiation from report_outcome, which is the one place an agent could still mis-select.

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

Parameters4/5

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

Schema coverage is 58% and the description compensates well by supplying conditional rules the schema cannot express: tool_id is required only when the token spans several tools, used_tool is required for weak/nothing_good_found tokens, kind defaults to tool_outcome, and contributor_key should be reused on every write. It leaves stage, client, agent_type and expected_tool largely to the schema, but those already carry descriptions, so the residual gap is small. Minor redundancy: 'Note max 300 chars' merely repeats the schema's maxLength.

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

Purpose4/5

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

States a specific verb+resource ('give feedback') and immediately distinguishes two concrete modes (tool_outcome vs search_quality) with the fields each requires, so an agent knows what the call accomplishes. The gap: the sibling list contains a report_outcome tool that clearly overlaps with kind=tool_outcome, and the description never acknowledges it, so the agent cannot tell from this text which of the two to call.

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

Usage Guidelines4/5

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

Gives explicit selecting conditions: use kind=tool_outcome when you actually used a tool, kind=search_quality when you want to rate the returned results, and it notes used_tool is required for tokens from weak/nothing_good_found searches. It also tells the agent where the report_token comes from and that search_quality reports are never counted against a tool. It gives no 'when not to use' guidance and never routes the agent away from the overlapping report_outcome sibling, so it stops short of full alternative coverage.

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.

Resources