Skip to main content
Glama

Agent Help Network

report_observation

Submit one de-identified firsthand observation under your own operating authority and platform rules. Public reports enter private review and are not site-status claims. Never include names, account details, URLs, cookies, tokens, or conversation text. Add cause with cause_basis only when you established the cause from one of the four listed bases, never as a guess; otherwise leave both out.

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": {
      "observation": "<observation>"
    },
    "name": "report_observation"
  }
}

Input Schema

NameRequiredDescriptionDefault
observationYesThe observation to submit: site_host, error_class and outcome are required; the other fields are optional and described one by one. Only coded values and the public hostname; no names, account details, URLs, cookies, tokens or conversation text.

Output Schema

NameRequiredDescriptionDefault
syntheticYes
incident_idYes
review_stateYes
observation_idYes
withdrawal_tokenNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed15 schema fields changed
    • addedInput schema / $defs / ObservationIn / properties / agent_family / description
      Added value: +"Which agent family you are: dots, muse, or other (the default; use it if neither fits)."
    • addedInput schema / $defs / ObservationIn / properties / attempt_actor / description
      Added value: +"Who made the attempt: agent (you, the default) or human (the person did it themselves)."
    • addedInput schema / $defs / ObservationIn / properties / attempt_env / description
      Added value: +"Where the attempt ran: agent_cloud_browser (a browser run by an agent in the cloud; needs attempt_actor agent), human_in_agent_browser or human_own_browser (a person at a browser; needs attempt_actor human), or unknown (the default)."
    • addedInput schema / $defs / ObservationIn / properties / challenge_kind / description
      Added value: +"What the challenge looked like: interactive_check (a box or puzzle to complete), loop (the check kept repeating), block_page (a page that only says access is denied), unknown, or none (the default; no challenge)."
    • addedInput schema / $defs / ObservationIn / properties / challenge_vendor / description
      Added value: +"Which bot-check provider showed a challenge: cloudflare, recaptcha, hcaptcha, unknown (a challenge from another or unclear provider), or none (the default; no challenge)."
    • addedInput schema / $defs / ObservationIn / properties / consent_confirmed / description
      Added value: +"Legacy field kept for older clients. It is not used to decide anything; leave it out."
    • addedInput schema / $defs / ObservationIn / properties / error_class / description
      Added value: +"What kind of stop it was: site_access (page or API refused or unreachable), login_auth (sign-in failed or an extra verification step appeared), human_verification (a CAPTCHA or a verify-you-are-human check), or service_error (the site returned an error or timed out)."
    • addedInput schema / $defs / ObservationIn / properties / idempotency_key / description
      Added value: +"A UUID that makes a resend safe: sending the same key with the same body again does not create a second record. Leave it out to get a new one."
    • addedInput schema / $defs / ObservationIn / properties / observed_at / description
      Added value: +"When the attempt happened, as an ISO 8601 time with a timezone offset, for example 2026-11-01T07:10:00Z. Leave it out for an attempt that just happened. Must be within the last 7 days and not in the future."
    • addedInput schema / $defs / ObservationIn / properties / outcome / description
      Added value: +"How the attempt ended: passed (it worked), blocked (the site or a check stopped it), error (it failed with an error), or abandoned (you or the person stopped before the end)."
    • addedInput schema / $defs / ObservationIn / properties / schema_version / description
      Added value: +"Report format version. Always 1; leave it out."
    • addedInput schema / $defs / ObservationIn / properties / site_host / description
      Added value: +"The public hostname the attempt was about, for example example.com. Only the host: no scheme, path, query, port or credentials."
    • addedInput schema / $defs / ObservationIn / properties / synthetic / description
      Added value: +"true only for a made-up test report. Leave it out (false) for a real attempt."
    • addedInput schema / $defs / ObservationIn / properties / task_step / description
      Added value: +"What you were trying to do, as a short lowercase code of letters, digits and underscores that starts with a letter, for example login, checkout or status_check. Default other."
    • addedInput schema / properties / observation / description
      Added value: +"The observation to submit: site_host, error_class and outcome are required; the other fields are optional and described one by one. Only coded values and the public hostname; no names, account details, URLs, cookies, tokens or conversation text."
  2. Changed4 schema fields changed
    • addedInput schema / $defs / CauseBasis
      Added value: +{
      +  "description": "D109: what the reporting agent established the cause from.",
      +  "enum": [
      +    "own_platform_message",
      +    "site_message",
      +    "person_confirmed",
      +    "compared_with_own_browser"
      +  ],
      +  "title": "CauseBasis",
      +  "type": "string"
      +}
    • addedInput schema / $defs / ObservationCause
      Added value: +{
      +  "description": "D109: the cause the reporting agent says it established, by the layer it points at. There is no \"unknown\" value: a\nreport that did not establish a cause leaves the field out.",
      +  "enum": [
      +    "site_said_no_agents",
      +    "site_bot_check",
      +    "site_unavailable",
      +    "platform_refused",
      +    "platform_needs_person",
      +    "verification_on_person_device",
      +    "verification_not_received",
      +    "signed_out",
      +    "agent_browser_differs"
      +  ],
      +  "title": "ObservationCause",
      +  "type": "string"
      +}
    • addedInput schema / $defs / ObservationIn / properties / cause
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/ObservationCause"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Optional, with cause_basis, for outcome blocked or error: the cause you established. Leave out if not established."
      +}
    • addedInput schema / $defs / ObservationIn / properties / cause_basis
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/CauseBasis"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Required with cause: what you established it from."
      +}
  3. Changed1 schema field changed
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +true
  4. First observed

TDQS

A3.7/5.0
Behavior4/5

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

The annotations already establish that this is a non-destructive, non-idempotent write into an open-world system. The description adds real context beyond that: reports go into private review, they are explicitly not site-status claims, and a hard prohibition on names, account details, URLs, cookies, tokens and conversation text. That is strong disclosure of post-submission handling and privacy constraints; only operational traits like rate limits or duplicate handling are absent.

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?

Four sentences, front-loaded with the action and the review model before the privacy and cause rules. Each sentence carries a distinct constraint — scope, post-submission behavior, PII prohibition, cause integrity — with little filler, though the cause sentence partially duplicates schema text.

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?

An output schema exists, so return values need not be explained, and the description correctly spends its space on submission constraints and the privacy boundary instead. For a single-nested-object write tool with rich annotations and full schema coverage, what is present is sufficient; the only gap is the absence of guidance relative to sibling tools.

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 description coverage is 100%, and every field in ObservationIn already carries a detailed inline description, so the schema is doing the heavy lifting. The description's contribution is the joint rule that cause and cause_basis must be supplied together and only when established from one of the four listed bases — useful emphasis, but largely a restatement of what the schema's field descriptions already say. Baseline 3 applies.

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?

The description opens with a specific verb and object: 'Submit one de-identified firsthand observation,' plus the scope qualifier 'under your own operating authority and platform rules.' That is unambiguous, but it never names or contrasts with the siblings (check_incident, rate_last_lookup), so it earns a 4 rather than a 5.

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

Usage Guidelines3/5

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

'Public reports enter private review and are not site-status claims' implicitly tells the agent this is not a status-checking tool, and the cause/cause_basis sentence gives an explicit conditional for the optional fields. However, there is no explicit statement of when to call this versus the sibling tools, and no stated prerequisites such as authentication or rate constraints, so the guidance remains implied rather than directive.

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.