Skip to main content
Glama
Sign In

HEY Research Lab

by io.github.hey-research-lab
OverviewDiscussionsAdmin

Explain a fact

explain_fact
Read-only

Why does HEY say a project is Shipping, Dormant or Still Building, or show a figure? The value, FACT, DERIVED or UNKNOWN, the rule and version, the winning source, the inputs, the lineage and the evidence ids. Omit fact to list what can be explained; source.counted takes a source id. build.change explains one change (event=, or the latest): its stage, who reported it, any exact release↔deployment link, what HEY does not know.

Input Schema

NameRequiredDescriptionDefault
factNoThe fact to explain; omit to list them.
slugYesA project slug, e.g. "agentos".
eventNoWith fact=build.change: a change-ledger id; omit for the latest.
sourceNoWith fact=source.counted: the source id.

Output Schema

NameRequiredDescriptionDefault
apiYes
dataNo
schemaYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / fact / description
      Added value: +"The fact to explain; omit to list them."
  2. Changed2 schema fields changed
    • addedInput schema / properties / event
      Added value: +{
+  "description": "With fact=build.change: a change-ledger id; omit for the latest.",
+  "maxLength": 240,
+  "type": "string"
+}
    • changedInput schema / properties / fact / enum
      Previous value: -[
-  "activity.status",
-  "build.momentum",
-  "still_building",
-  "research.level",
-  "token.verification",
-  "source.counted"
-]New value: +[
+  "activity.status",
+  "build.momentum",
+  "still_building",
+  "research.level",
+  "token.verification",
+  "source.counted",
+  "build.change"
+]
  3. Changed1 schema field changed
    • changedInput schema / properties / fact / enum
      Previous value: -[
-  "market.valuation",
-  "market.status",
-  "activity.status",
-  "build.momentum",
-  "discovery_gap",
-  "still_building",
-  "research.level",
-  "token.verification",
-  "source.counted",
-  "market_integrity.state"
-]New value: +[
+  "activity.status",
+  "build.momentum",
+  "still_building",
+  "research.level",
+  "token.verification",
+  "source.counted"
+]
  4. Changed2 schema fields changed
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "api": {
+      "type": "string"
+    },
+    "data": {},
+    "schema": {
+      "const": "hey.mcp-api-answer",
+      "type": "string"
+    }
+  },
+  "required": [
+    "schema",
+    "api"
+  ],
+  "type": "object"
+}
  5. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already mark the tool read-only and open-world; the description adds meaningful behavioral detail about what is returned, including derived vs unknown values, winning source, rule version, lineage, and evidence ids, and notes what HEY does not know for build.change. It does not cover permissions, rate limits, or pagination, but those are secondary given the annotations and output schema.

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?

Three sentences, front-loaded with the user-facing question and then output and mode details; no filler. The dense fragments and question format are slightly less direct than a plain verb-first statement, but the description remains compact.

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 four-parameter read-only provenance tool with complete input schema coverage and an output schema, the description covers purpose, output shape, list mode, and conditional parameters. It could be stronger by routing among sibling tools, but nothing essential to invoking it correctly is missing.

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% and each parameter already has a description, so the description's parameter guidance is mostly reinforcement. It adds cross-parameter context for source.counted and build.change but does not give syntax beyond the schema, so the 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?

States a specific verb ('explain') and resource ('fact') and details the output components such as value, derivation, rule/version, winning source, lineage, and evidence ids. It clearly distinguishes listing facts from explaining a specific fact, but does not explicitly differentiate itself from sibling evidence or change tools.

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?

Provides conditional usage for optional parameters: omit fact to list what can be explained, source.counted takes a source id, and build.change explains one change via event id or the latest. It does not say when to prefer this tool over get_evidence, get_changes, or other siblings, leaving alternative selection to inference.

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

All HEY Research Lab toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources