Skip to main content
Glama
no-materials

Hirð

by no-materials
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Explain effect row

explain_effect_row
Read-onlyIdempotent

Get a function's effect row with plain-language explanations of each effect, revealing what the function may do. Ideal for interpreting unfamiliar effects.

Instructions

Explain a function's effect row: the canonical row plus a one-sentence explanation of each effect. Use it for 'what may this function do' or to interpret an unfamiliar effect. It covers one named function (a tool name explains the tool's generated function, Tool<Name> included); use infer_type for an arbitrary expression's row and emit_actor_effect_graph for what an actor transitively does. Returns name (the function explained), type, effect_row, open (the row ends in a row variable, so it may carry more effects than listed), pure (closed and empty), and effects, each with effect and explanation. A name that is not a function (a type, an actor, …) is not_a_function; an unknown name is not_found with the available names in error.data.available. Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fileYesPath to a .hird source file, absolute or relative to the server's working directory. Every .hird file in its directory is compiled with it as one program, so imported names resolve; answers may name a sibling file.
fn_nameYesThe function's name, as the file's source would write it: a local definition, a member imported with `use Mod.{name}`, or `Qualifier.name` through `use Mod`.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
fileYes
nameYes
openYes
pureYes
typeYes
effectsYes
effect_rowYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / file / description
      Previous value: -"Path to a .hird source file. Its directory's .hird files are compiled together as one program, so imported names resolve."New value: +"Path to a .hird source file, absolute or relative to the server's working directory. Every .hird file in its directory is compiled with it as one program, so imported names resolve; answers may name a sibling file."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "effect_row": {
+      "type": "string"
+    },
+    "effects": {
+      "items": {
+        "properties": {
+          "effect": {
+            "type": "string"
+          },
+          "explanation": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "effect",
+          "explanation"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "file": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "open": {
+      "type": "boolean"
+    },
+    "pure": {
+      "type": "boolean"
+    },
+    "type": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "effect_row",
+    "effects",
+    "file",
+    "name",
+    "open",
+    "pure",
+    "type"
+  ],
+  "type": "object"
+}
  2. Changed2 schema fields changedv0.1.1
    • changedInput schema / properties / file / description
      Previous value: -"Path to a .hird source file."New value: +"Path to a .hird source file. Its directory's .hird files are compiled together as one program, so imported names resolve."
    • changedInput schema / properties / fn_name / description
      Previous value: -"The function's name."New value: +"The function's name, as the file's source would write it: a local definition, a member imported with `use Mod.{name}`, or `Qualifier.name` through `use Mod`."
  3. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description complements these with specific context: it compiles the file's directory in memory with a cache until a sibling changes, and writes or executes nothing. It also details failure modes, including stable error.codes and the consistent shape of error.data.diagnostics. This goes beyond the annotations and gives the agent an accurate model of what the tool does under the hood.

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?

The description is dense and information-rich, but it is also lengthy and slightly run-on. It front-loads the core purpose and usage, then flows into behavioral details and error codes. Although every sentence adds value, the structure could be improved with clearer separation (e.g., bullets) to reduce cognitive load. It remains within acceptable bounds for a complex tool.

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

Completeness5/5

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

The description is exhaustive for its complexity. It covers the return value structure (name, type, effect_row, open, pure, effects), the edge cases (not_a_function, not_found), and all possible error codes with their data shape. Combined with the rich output schema and the annotations covering resource safety, an agent has everything needed to call the tool correctly and interpret results. Nothing material is missing.

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 description coverage is 100%, so the schema already documents both parameters. Still, the description adds meaning: it clarifies that `file` can be relative to the server's working directory and that sibling files are compiled together, so names may resolve to other files. For `fn_name`, it specifies the syntax for imports and qualifiers, which is not in the schema. Despite high coverage, this added context justifies a score above baseline 3.

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?

The description opens with a precise verb–object pair ('Explain a function's effect row') and immediately defines what it covers: the canonical row plus a one-sentence explanation of each effect. It clearly identifies the target resource (a single named function) and differentiates itself from siblings by naming alternatives (infer_type, emit_actor_effect_graph). It also specifies edge cases (not_a_function, not_found), leaving no ambiguity about what the tool does.

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?

The description gives explicit guidance on when to use this tool: for 'what may this function do' or interpreting unfamiliar effects. It explicitly names alternatives and the conditions that select them: use infer_type for an arbitrary expression's row, and emit_actor_effect_graph for an actor's transitive effects. This actionable routing leaves no inference to the agent.

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

Deploy Server

Other Tools