Hirð

Overview Schema Source Related Servers Discussions Admin

Look up definition

lookup_definition

Read-onlyIdempotent

Look up a top-level definition by name in a Hirð file to get its defining file, line, kind, type, and doc comment. Use it to identify a symbol before exploring its effects, callers, or IR.

Instructions

Look up a top-level definition by name: defining file and line, kind, type, and doc comment. Use it first to locate or identify a symbol; use get_context_for_symbol when you also want effects, callers, and callees, explain_effect_row to interpret a function's effects, and render_ir_fragment for its body. Returns kind (function, type, type alias, constructor, effect, tool, tool_function, actor, message_type, message_constructor, supervisor, or extern), line, and nullable type (for a type alias, the type it expands to) and doc; file is the sibling module when the name is imported. An unknown name is not_found, with every name in the file's scope 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

Name	Required	Description	Default
`file`	Yes	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.
`name`	Yes	The definition'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

Name	Required	Description	Default
`doc`	No
`file`	Yes
`kind`	Yes
`line`	Yes
`name`	Yes
`type`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 4, 2026

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": {
+    "doc": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "file": {
+      "type": "string"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "line": {
+      "type": "integer"
+    },
+    "name": {
+      "type": "string"
+    },
+    "type": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "file",
+    "kind",
+    "line",
+    "name"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedv0.1.1Aug 28, 2026

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 / name / description

Previous value: -"The definition's name."New value: +"The definition'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`."

First observedv0.1.0Aug 24, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral context beyond that: it compiles the file's directory in memory, is cached until a sibling changes, writes or executes nothing, returns not_found for unknown names, and exposes stable error codes. This exceeds the coverage provided by annotations alone.

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?

The description is long but every sentence earns its place: purpose first, then sibling routing, then return shape, unknown-name behavior, read-only guarantee, and error code taxonomy. It is dense, well-ordered, and free of filler.

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?

Given the tool's complexity, the output schema, and the annotation context, the description is complete: it covers return values, naming semantics, imported-name behavior, failure modes, caching, and relationships to sibling tools. An agent has all the information needed to invoke it correctly.

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 the input schema's parameter descriptions are already rich, so the description does not need to add much. It contributes some framing by noting the lookup is by name and clarifying that the name is written as the source would write it, but the schema carries the main burden.

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 states a specific verb-resource pair ('Look up a top-level definition by name') and enumerates exactly what the tool returns: defining file/line, kind, type, and doc comment. It further distinguishes itself from siblings such as get_context_for_symbol and render_ir_fragment, so an agent can select it without ambiguity.

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 explicitly says to use this tool first to locate or identify a symbol and names the alternatives for additional needs: get_context_for_symbol for effects/callers/callees, explain_effect_row for behavior, and render_ir_fragment for the body. This gives clear when-to-use and when-not-to-use guidance.

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

Deploy Server