naja-scope is an MCP server that lets AI assistants navigate and analyze elaborated SystemVerilog designs and gate-level netlists through structured queries — without pasting source files into context.
Load Designs
Elaborate SystemVerilog RTL (load_systemverilog) or load gate-level/structural Verilog netlists (load_verilog)
Load Liberty cell libraries (load_liberty) or built-in/custom primitive sets (load_primitives)
Save/load snapshots (save_snapshot / load_snapshot) for fast reload without re-elaboration
Reset all loaded designs and session state (reset_universe)
Navigate Hierarchy
Resolve hierarchical paths with glob support and did-you-mean suggestions (resolve)
Search design-wide by name/kind — instance, net, port, module (find)
Walk the module/instance tree to any depth (get_hierarchy)
Get structured module summaries: ports, instance counts, sequential count, clock/reset candidates (get_module_card)
Aggregated instance count statistics under any hierarchy node (get_stats)
Trace Connectivity & Logic Cones
Find what drives any net/term across hierarchy boundaries (get_drivers)
Find what any net/term feeds, across hierarchy (get_loads)
Trace combinational fan-in/fan-out cones stopping at registers, top ports, and blackboxes, with cross-hierarchy frontier grouping (trace_cone)
Source & Design Intent
Retrieve exact SystemVerilog source lines (file + line range) for any design object (get_source)
Recover design intent lost during elaboration: enum/typedef state names and encodings, struct fields, symbolic parameter expressions, FSM states (get_intent)
Escape Hatch
Run arbitrary Python directly against the live design (query_python) — unsandboxed, opt-in via NAJA_SCOPE_ENABLE_PYTHON=1
Let your AI assistant explore SystemVerilog designs — without pasting source code into the chat.
naja-scope is an MCP server that gives AI agents (Claude, and any MCP-compatible assistant) a precise, structured view of your elaborated SystemVerilog design. Instead of dumping thousands of lines of RTL into the model's context, the agent asks targeted questions — what drives this signal? what's inside this module? where does this net come from? — and gets back small, exact answers with file-and-line references.
Built on the najaeda netlist engine.
Large designs don't fit in a chat window. Pasting RTL is slow, expensive, and the model still can't reliably trace connectivity across hierarchy. naja-scope turns your design into something an agent can navigate:
🔎 Trace connectivity — find what drives or loads any signal, across module boundaries.
🌲 Walk the hierarchy — explore modules, instances, and ports on demand.
🎯 Jump to source — every answer comes with file:line ranges, so the
agent can quote the exact RTL that matters.
🧩 Logic cones — trace fan-in / fan-out combinational cones up to the register boundary.
💡 Recover design intent — enum state names, struct/union fields, and parameter formulas that normally vanish when a design is elaborated.
Works on RTL and gate-level netlists alike: load elaborated SystemVerilog, or load a post-synthesis structural Verilog netlist together with its Liberty standard-cell library and navigate the gates the same way (see Gate-level designs).
All responses are token-bounded: lists paginate, large results truncate with clear markers. Your context stays small; your answers stay accurate.
Related MCP server: Universal Netlist MCP Server
We ran a head-to-head on CVA6 (a
production RISC-V core): the same 17 design questions, answered by Claude once
with only naja-scope and once with only grep/file reading over the
source tree.
Approach | Correct answers | Conversation turns | Input tokens |
naja-scope | 17 / 17 | 77 | 182 k |
grep + read source | 10 / 17 | 123 | 888 k |
More correct answers, fewer back-and-forth turns, and ~5× fewer tokens — the agent stops scrolling through files and goes straight to the structural answer.
pip install naja-scope # pulls najaeda and the MCP runtime from PyPI
naja-scope-mcp # stdio MCP serverclaude mcp add naja-scope -- naja-scope-mcpOr add it to any MCP client's config:
{
"mcpServers": {
"naja-scope": {
"command": "naja-scope-mcp"
}
}
}Then just ask your assistant to load a design and start exploring:
"Load my UART design from
rtl/uart.svwith topuart_top, then show me everything that drivestx_o."
The agent loads the design once and answers follow-up questions instantly — no re-reading source, no giant pastes.
ChatGPT connects to MCP servers over an HTTP endpoint (custom connectors / Developer mode), so run naja-scope as an HTTP server instead of stdio:
naja-scope-mcp --transport streamable-http --host 127.0.0.1 --port 8000This serves MCP at http://<host>:8000/mcp. Because ChatGPT reaches the server
over the network, expose that URL where ChatGPT can see it — e.g. a public
tunnel for a local run:
# example: a tunnel to your local server (ngrok, cloudflared, …)
ngrok http 8000 # -> https://<something>.ngrok.app → add /mcpThen in ChatGPT, open Settings → Connectors (enable Developer mode if
needed), add a custom connector, and paste the server URL
(https://<your-host>/mcp). Once connected, ask it to load a design and explore
exactly as above. (ChatGPT's connector UI evolves; the constant is: it needs an
HTTPS MCP URL, which --transport streamable-http provides.)
⚠️ The HTTP server has no built-in auth — only expose it over a trusted tunnel, and prefer short-lived tunnels for local experiments.
Already synthesized? Load the structural Verilog netlist together with the Liberty library that defines its standard cells, and navigate the gates the same way as RTL:
"Load the Liberty library
pdk/stdcells.lib, then the gate netlistbuild/top.v, and tell me what cellstopis built from and what drivesdata_out."
Hierarchy, per-cell counts (get_module_card), drivers/loads, and logic cones
all work on the netlist; cones stop at the sequential cells. A gate netlist
carries no source line info, so get_source applies to RTL only. A runnable
example lives in examples/ (stdcells.lib + counter2.v +
gate_level.py).
Once a design is loaded, your assistant can:
Resolve any signal or instance by hierarchical path (with glob and did-you-mean suggestions).
Find objects design-wide by pattern.
Show the hierarchy of any module.
Get drivers / loads of a net — the real endpoints, across hierarchy;
literal drivers preserve four-state 0 / 1 / X / Z values.
Trace logic cones (fan-in / fan-out) and see the register frontier.
Get source — the exact SystemVerilog lines behind any object.
Get a module card — ports, counts, clock/reset at a glance.
Recover design intent — state-machine names, struct fields, parameter expressions lost during elaboration.
A runnable end-to-end walkthrough lives in examples/, including
versions that run against CVA6 (a
production RISC-V core, cloned on demand — see
examples/cva6_demo.sh) and
CORE-V-MCU (a full multi-vendor
RISC-V SoC — see examples/core_v_mcu_demo.sh).
naja-scope also has a query_python tool that runs Python directly against the
loaded design, for queries the typed tools above cannot express. It is not
registered unless you opt in:
NAJA_SCOPE_ENABLE_PYTHON=1 naja-scope-mcpIt is unsandboxed eval/exec inside the server process — read-only by
convention, not enforced — so anything that can reach the server can run
arbitrary Python as the server's user. That matters most under --transport streamable-http, where the server listens on a socket. Leave it off unless you
need it and trust every client that can reach the endpoint.
Python 3.10+
Works anywhere najaeda runs (Linux, macOS, Windows)
# from a checkout
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m pytest -qThe full test suite runs against a plain pip install of najaeda — no native
build required. The CVA6 cross-hierarchy cone regression
(tests/test_zzz_cone_cva6.py) is slow and skips automatically unless a CVA6
snapshot is present.
🐛 Found a bug or have a feature request? Open an issue on GitHub →
📫 Get in touch: contact@keplertech.io
Apache-2.0. See LICENSE.
Glob search names design-wide (pattern with '.' matches full paths). kind: instance|net|port|module|any. Paginated via cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | any | |
| limit | No | ||
| cursor | No | ||
| pattern | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It states that the tool performs a glob search (likely read-only) and is paginated via cursor, which implies idempotency. However, it does not explicitly state that the tool has no destructive side effects, which would be helpful for an agent's decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of two short sentences. It front-loads the primary action ('Glob search names design-wide'), then adds detail about dot patterns, kind values, and pagination. Every sentence provides value, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool having no output schema, the description does not explain what the search results look like (names, paths, or IDs). It also fails to mention whether the search is case-sensitive, matches partial names, or returns exact matches. For a search tool, these details are important for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameter meanings. It explains 'pattern' as a glob search (including the special meaning of dots for paths) and 'kind' by listing valid values. However, it only mentions pagination via 'cursor' without explaining how to use the 'limit' or 'cursor' parameters, leaving two of four parameters partially documented. This is insufficient for a tool with no schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a glob search for names design-wide, specifying that a pattern with a dot matches full paths. It lists the valid kinds (instance, net, port, module, any), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'resolve' or 'trace_cone' that might also involve searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description mentions pagination via cursor but does not explain the typical use case or prerequisites. There is no indication of when not to use it, leaving the agent to infer context without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What drives this term/net, through the equipotential: leaf drivers
(FF/gate instances with pin, model, source ref) and top-level ports.
Capped at limit (default 50, max 200) with a truncated flag; no cursor —
raise limit to see more.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description is the sole source. It discloses limit behavior (capped at 50, max 200, truncated flag, no cursor) and the types of drivers returned. However, it does not mention read-only nature, permission requirements, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. The first sentence packs a lot of specificity, but the phrasing is slightly fragmented ('What drives this term/net'). No wasted words; front-loads the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 params, no output schema, 0% schema coverage), the description explains the driver types and limit behavior but lacks detail on the output structure (e.g., list format) and exact meaning of `path`. Some gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains the `limit` parameter (default 50, max 200) but does not provide details about the `path` parameter beyond implying it is the term or net. Some value added but incomplete for both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns drivers for a term/net, specifying leaf drivers (FF/gate instances with pin, model, source ref) and top-level ports. It distinguishes from siblings like `get_loads` (loads). The verb is implied but the resource and scope are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining drivers, but no explicit when-to-use or when-not-to-use vs alternatives like `get_loads` or `get_source`. No exclusions or context for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hierarchy tree under an instance (default top). Lists only non-assign
children (real submodules + leaf primitives); assign glue is reported as
assign_count, not enumerated. Each child carries a leaf flag (submodule
vs leaf primitive). depth<=5; the non-assign set is paginated at the root
via limit/cursor (next_cursor/has_more), deeper levels via children_truncated.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| depth | No | ||
| limit | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses: lists only non-assign children, assign_count, leaf flag, depth<=5, pagination at root via limit/cursor and deeper via children_truncated. Thorough and accurate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences packed with information, well-structured: main purpose first, then details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains output structure (leaf flag, assign_count) and pagination. Covers behavior comprehensively for a hierarchy tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters. It mentions path (default top), depth (<=5), limit and cursor for pagination, but doesn't explicitly define each parameter's role. Adds partial meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a hierarchy tree under an instance, specifying it lists non-assign children, how assign is handled, leaf flag, depth limit, and pagination. It distinguishes from sibling tools like find or get_drivers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining hierarchical structure without assign enumeration, but doesn't explicitly say when to use this vs alternatives. Context is clear, but no exclusions given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Source-level INTENT a netlist erases in lowering (warm-only). Use when the answer is in the SystemVerilog type/declaration, not the flattened gates: enum/typedef state names + encodings (incl. PACKAGE typedefs whose members live in another file), and symbolic PARAMETER expressions (the formula behind a baked-in width). ref: a hierarchical path ('cva6.csr_regfile_i.priv_lvl_q'), a package member ('riscv::PLEN'), or an instance path for its parameters. want: auto | type | fsm_states | parameters. If the intent layer is not loaded, returns a note and you should fall back to get_source.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | ||
| want | No | auto |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that it is 'warm-only' and what it returns (enum/typedef states, parameters). However, the phrasing 'Source-level INTENT a netlist erases in lowering' is confusing and lacks clarity on side effects, permissions, or error behavior. More transparency on conditions and constraints would improve this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise given the tool's complexity. It front-loads the core purpose and follows with usage details. Some phrases are dense (e.g., 'Source-level INTENT a netlist erases in lowering') which could be streamlined, but overall no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is present, so the description must explain return values. It describes that the tool returns enum/typedef state names and encodings, and symbolic parameter expressions. It also mentions error handling (note when intent layer not loaded). While not exhaustive about structure, it provides sufficient context for an AI agent to understand the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the ref parameter with examples of acceptable formats (hierarchical path, package member, instance path) and lists valid values for want ('auto', 'type', 'fsm_states', 'parameters'). This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves source-level intent (type/declaration info) from a netlist, specifying it operates on SystemVerilog types and parameters rather than flattened gates. It provides concrete examples of ref and want, making the purpose unambiguous and distinct from siblings like get_source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool: when the answer is in SystemVerilog type/declaration, not flattened gates. Also provides fallback guidance: if intent layer not loaded, fall back to get_source. This clearly distinguishes it from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What this term/net feeds, through the equipotential: leaf readers
(instances with pin, model, source ref) and top-level ports. Mirror of
get_drivers; same limit/truncated capping.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'limit/truncated capping', indicating some behavioral trait, but does not disclose whether the tool is read-only, requires specific permissions, or has side effects. The behavior is only partially addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) but at the cost of clarity. It is cryptic and uses unclear phrasing, making it not concise in an informative sense. Every sentence should earn its place, but here the first sentence is confusing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no output schema, and moderate complexity (netlist terms), the description is severely incomplete. It does not explain return value, expected inputs, or how the tool integrates with siblings. The agent lacks sufficient context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It only mentions 'limit/`truncated` capping' but does not describe the 'path' parameter or provide syntax/format details. The description fails to add meaning beyond the schema for either parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses domain-specific jargon ('equipotential', 'leaf readers') without defining the action clearly. It vaguely states what the tool returns but does not explicitly state the verb or resource. The reference to 'Mirror of get_drivers' provides some context, but the purpose remains unclear for an AI agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Mirror of get_drivers' as a sibling, hinting at similarity, but provides no explicit guidance on when to use this tool versus alternatives. No usage conditions or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deterministic module summary: ports, instance counts by model, sequential count, source ref, plus clock/reset candidates — a name-based regex guess, not a structural result; verify before relying on it.
| Name | Required | Description | Default |
|---|---|---|---|
| module | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavior: deterministic but caveat about regex-based guesses. It alerts users to potential inaccuracies, which is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that packs essential information without redundancy, achieving high conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key output elements but omits details like return format or error cases. Given the tool's simplicity and lack of output schema, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single 'module' parameter is not elaborated beyond the schema (0% coverage), but its usage is intuitive. The description implies it accepts a module name, which is sufficient for a simple string input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly lists the output items (ports, instance counts, sequential count, source ref, clock/reset candidates) and distinguishes it from sibling tools like get_stats or get_hierarchy by specifying a deterministic module summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description warns that clock/reset candidates are a name-based regex guess and advises verification before reliance, implying limited trustworthiness for structural queries. However, it does not explicitly name alternative tools for deeper analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SystemVerilog source lines that produced an object (FF instance -> its always_ff block). Returns file, range, text.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| context_lines | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses that it returns file, range, and text, which is helpful. However, it does not address error behavior (e.g., if path does not exist), performance characteristics, or side effects. The description provides moderate transparency but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) and front-loaded with the core purpose. However, it omits crucial information about parameters and usage, making it under-informative. Conciseness is positive, but completeness suffers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 params, no output schema), the description explains the output structure and provides an example, which is helpful. But it lacks parameter descriptions and error handling context, leaving gaps for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain what 'path' or 'context_lines' mean. The parameter semantics are entirely missing; the description only mentions output, not input. With 2 parameters and no explanation, this is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving SystemVerilog source lines for an object, with a specific example (FF instance to always_ff block). It is specific about the verb ('get') and resource ('source lines'), and the output fields (file, range, text) inform the agent. However, it does not explicitly differentiate from sibling tools, though the purpose is unique enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_hierarchy or trace_cone. There is no mention of prerequisites, limitations, or context where this tool is preferred. The agent must infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregated instance statistics per model under an instance (default top). Paginated.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| limit | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It notes the tool is paginated but does not describe whether it is read-only, what the statistics include, how default top works, or any limitations. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two fragments), which is concise but lacks necessary detail. It front-loads key words like 'aggregated instance statistics' but omits crucial information. The structure is acceptable given the brevity, but the content is insufficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters with no descriptions, no output schema, no annotations), the description is incomplete. It doesn't explain the output format, default behavior, or how pagination works. The information provided is not enough for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It only vaguely mentions 'per model under an instance (default top)', which relates to the 'path' parameter but is unclear. No explanation for 'limit' or 'cursor' beyond the word 'paginated'. The description adds almost no value to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool provides aggregated instance statistics per model, which indicates the resource but lacks an explicit verb like 'retrieve' or 'get'. It mentions pagination and a default 'top' instance, which adds context. However, it does not clearly say what the tool does, making it slightly vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_drivers, get_hierarchy, etc. The description only mentions pagination, but does not distinguish the tool's purpose from siblings or specify prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make the warm intent layer available for get_intent (naja's in-engine SNL↔slang link). No-op if a load already retained it; otherwise re-elaborates WITH the link from the captured flist/files (pass them after a cold snapshot).
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| files | No | ||
| flist | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses idempotency (no-op if already retained) and re-elaboration behavior. However, it omits details on side effects, permissions, or error handling, which are needed for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose. It avoids extraneous words, but the brevity sacrifices clarity for some readers. Still, it's efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description uses domain jargon ('warm intent layer', 'cold snapshot', 'SNL↔slang link') without elaboration. With no output schema and many sibling tools, this fails to fully orient an AI agent on how and when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It mentions 'flist/files' as captured inputs, hinting at their role, but does not explain 'top'. This partial compensation is insufficient for the 3 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: making the warm intent layer available for get_intent. It adds context about no-op behavior and re-elaboration, which helps differentiate from simple load operations. However, it does not explicitly distinguish from all siblings like get_intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context (after a cold snapshot, pass flist/files) but does not explicitly state when to use this over alternatives like load_snapshot or get_intent. It hints at prerequisites but lacks clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load Liberty cell libraries (defines primitives for gate netlists).
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states loading and definition purpose. No mention of side effects, state changes, or required conditions. Minimal behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded, but could be slightly more informative without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description lacks details on return values, error conditions, and file format. For a simple tool it is incomplete; agent may need to infer behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The lone parameter 'files' is not described in the description despite 0% schema coverage. No explanation of file paths, format, or expected count.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool loads Liberty cell libraries and defines primitives for gate netlists. It is specific to Liberty format, but doesn't explicitly differentiate from sibling 'load_primitives'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives (e.g., load_verilog, load_primitives) or prerequisites. The description implies usage for Liberty libraries but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load primitives: built-in by name ('xilinx'|'yosys') or a Python file defining load(db).
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states the action and sources, lacking details on side effects, permissions, error handling, or what happens if both parameters are given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear, front-loaded purpose. Every word is informative, no redundancy or irrelevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Essential functionality is described, but lacking details about what primitives are, preconditions, or return behavior. Without output schema, more context would be beneficial for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds value by specifying valid built-in names for 'name' and the expected interface for 'file' (a Python function). Still does not explain type constraints or mutual exclusivity fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool loads primitives via two methods: built-in by name (enumerating 'xilinx' and 'yosys') or from a Python file. This distinguishes it from sibling load tools for different data types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies two usage modes but provides no guidance on when to choose one over the other, nor any comparison with other load tools (load_liberty, load_verilog, etc.).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reload a save_snapshot directory in seconds (no re-elaboration). intent=True also re-elaborates the warm intent layer from the flist saved in the snapshot (for get_intent).
| Name | Required | Description | Default |
|---|---|---|---|
| intent | No | ||
| directory | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes key behavioral traits: fast reload, no re-elaboration unless intent=True. No annotations provided, so description carries full burden and adds value beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with primary purpose, no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers tool behavior and parameter effects, but lacks prerequisites (e.g., snapshot must exist) and return value info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Explains the intent parameter's effect (re-elaborate warm intent layer) beyond schema; directory parameter is self-explanatory from context. Schema coverage is 0%, so description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Reload a save_snapshot directory in seconds (no re-elaboration)' with a specific verb and resource, and distinguishes from siblings by highlighting speed and lack of full re-elaboration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context for when to use (reload snapshot) and behavior of intent parameter, but does not explicitly state when not to use or mention alternatives like load_intent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Elaborate SystemVerilog (files and/or an flist; optional top module). Anonymous lowered objects are addressable by #. intent=True retains naja's in-engine SNL↔slang link for get_intent.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| files | No | ||
| flist | No | ||
| intent | No | ||
| keep_assigns | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions that anonymous lowered objects are addressable by '#<id>' and that 'intent=True' retains a link for 'get_intent'. However, it does not disclose side effects, required permissions, or error behaviors, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of three sentences that front-load the main action and provide key details. There is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, no annotations, no output schema), the description lacks completeness. It does not explain return values, error handling, or the purpose of the 'keep_assigns' parameter. The tool feels under-documented for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description partially adds meaning: it explains that 'top' is optional, 'files' and 'flist' can be used together, and 'intent' controls a link. However, it does not explain the 'keep_assigns' parameter, which is critical for understanding the tool's behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool elaborates SystemVerilog using files or flist with an optional top module. It uses a specific verb ('Elaborate') and resource, and distinguishes it from siblings like 'load_verilog' (different language) and 'load_snapshot' (loading pre-compiled).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives such as 'load_verilog' or 'load_liberty'. It lacks prerequisites, context of use, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load gate-level/structural Verilog netlists. Pair with load_liberty (or load_primitives) so cells resolve to real models; allow_unknown_designs=True blackboxes any module still undefined instead of failing. Gate netlists carry no source info, so get_source/get_intent cannot answer for them.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | ||
| keep_assigns | No | ||
| allow_unknown_designs | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that gate netlists carry no source info (so get_source/get_intent cannot answer) and explains the allow_unknown_designs flag effect. But it does not mention if loading is cumulative, idempotent, or what happens on error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loading the core purpose. Every sentence adds value: main action, pairing/flag behavior, and a limitation. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the main use case and a key limitation. However, it lacks details on keep_assigns behavior, cumulative loading, and error handling, leaving moderate gaps for a loading tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description should document parameters. It only explains allow_unknown_designs. The files parameter is implied but not explicitly described; keep_assigns is entirely omitted. This leaves significant gaps for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it loads 'gate-level/structural Verilog netlists', giving a specific verb and resource. It distinguishes from sibling tools like load_systemverilog by specifying 'structural' and mentioning pairing with load_liberty/load_primitives, which are also siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: pair with load_liberty or load_primitives, and describes allow_unknown_designs behavior. However, does not explicitly state when not to use (e.g., for behavioral code) or name alternatives beyond the pairing siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: run Python against the live design ('naja' raw bindings, 'snl' raw helpers, 'session', 'top' in scope). Prefer the typed tools above; use this only for queries they cannot express. Unsandboxed eval/exec in the server process — read-only by convention, not enforced; operators can turn it off with NAJA_SCOPE_DISABLE_PYTHON. Output capped.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits: it is an unsandboxed eval/exec in the server process, read-only by convention but not enforced, and output is capped. No annotations were provided, so the description fully covers the safety and execution model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, each adding value. It is front-loaded with verb and scope, and no extraneous information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the dangerous nature of the tool (unsandboxed eval), the description covers its purpose, usage guidelines, behavioral traits (safety, output cap), and disable mechanism. No output schema is provided, but output behavior is described. The description is complete for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'code' has no schema description (0% coverage), but the description adds meaning by explaining that the code is Python executed in a specific scope with raw bindings. This provides sufficient context for the agent to understand how to use the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as an 'escape hatch' for running Python against the live design, specifying the verb (run Python), resource (live design), and scope (bindings, session, top). It also distinguishes itself from sibling tools by instructing to prefer typed tools above and use this only for queries they cannot express.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('only for queries they cannot express') and when not to ('Prefer the typed tools above'). It also mentions that operators can disable it via an environment variable, providing clear guidance on appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear all loaded designs and session state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the action (clear) but lacks details on irreversibility, side effects, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words, front-loads the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no parameters, the description is adequate for a simple destructive operation, though it could mention confirmation or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the schema provides no information. The description meaningfully explains the tool's effect ('clear all loaded designs and session state'), earning a baseline 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'clear' and the resources 'all loaded designs and session state', making it distinct from sibling tools that load or query data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a hierarchical path (e.g. 'top.u_uart.tx_o', bit selects and glob in last segment OK) to instance/term/net descriptors with source refs. On failure returns did-you-mean suggestions. kind: instance|term|net.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| path | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It discloses that the tool returns descriptors with source refs, handles failures with suggestions, and accepts a kind filter. While it does not mention read-only status or performance characteristics, it provides sufficient behavioral detail for a query-like tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences plus a trailing snippet. It is front-loaded with the core action and example. The trailing 'kind: instance|term|net.' could be integrated but overall is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not explain the return format of 'descriptors' or 'source refs', which is important since there is no output schema. It also lacks details on the did-you-mean mechanism and how 'limit' affects results. For a tool performing resolution, this leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for 'path' (with example) and 'kind' (possible values listed), but does not explain the 'limit' parameter. Since schema coverage is 0%, the description partially compensates but leaves one parameter undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves a hierarchical path to descriptors with source refs, and provides an example ('top.u_uart.tx_o'). It also mentions the output kinds (instance/term/net). However, it does not explicitly differentiate from sibling tools like 'find', leaving some ambiguity about when to use this tool over others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the primary use case (resolving a path) and mentions error handling (did-you-mean suggestions), but does not provide guidance on when to use this tool versus alternatives (e.g., 'find' or 'get_hierarchy'). No explicit 'when-not-to-use' or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist the design + source index for fast reload (naja-if + sidecar). Tied to the producing najaeda version — load_snapshot rejects a foreign one.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool persists data to a directory and is version-sensitive, but does not detail side effects, permissions required, or the exact behavior beyond saving. Without annotations, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, each essential: the first states the core action, the second adds an important constraint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (1 param, no output schema), but the description lacks parameter details and does not mention return value or error conditions. It does provide the version constraint, which is helpful context for usage with load_snapshot.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'directory' is not described in the schema (0% coverage) and the description provides no additional meaning about its expected format, purpose, or behavior. The agent is left guessing what 'directory' refers to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Persist the design + source index') and the purpose ('fast reload'). It distinguishes itself from sibling tool 'load_snapshot' by referencing it and noting version compatibility, making its role unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to save for fast reload) and provides a key constraint (version tie-in with load_snapshot rejecting foreign versions). However, it does not explicitly state when not to use or list alternative tools beyond load_snapshot.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current session: loaded design summary, and whether the intent
layer is live (intent_loaded) / re-loadable (intent_loadable).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It indicates the tool returns session status, which is likely read-only, but does not explicitly state safety, idempotency, or any constraints. The description lacks depth on behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single sentence that front-loads the key information ('Current session:'). Every word earns its place, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (no parameters, no output schema), the description adequately explains the return values. However, it does not differentiate from sibling tools like 'get_intent' or 'get_loads', leaving some context missing for optimal selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is vacuously 100%. Per rubric, absence of parameters yields a baseline of 4. The description does not add parameter semantics, but that is acceptable given no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns the current session's loaded design summary and intent layer status. It uses specific terms like 'intent_loaded' and 'intent_loadable', making the purpose evident. However, it could be more explicitly phrased as a verb action (e.g., 'get status'), but the intent is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_intent' or 'get_loads'. It does not specify prerequisites, side effects, or comparative advantages, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trace the combinational fanin/fanout cone of a term/net via naja's
LogicCone. direction: fanin|fanout. The cone crosses hierarchy and
combinatorial arcs and always stops at flops, top ports, and opaque
black-box cells. Returns node_count, counts_by_kind, counts_by_model, and a
frontier of {flops, ports, blackboxes} with exact counts and lists capped
at max_frontier (<=200) with a truncation marker.
cross_hierarchy groups the flop frontier by top-level submodule and, under
outside_root_subtree, names the frontier registers that live OUTSIDE the
cone root's own subtree (the cross-hierarchy answer) — read it directly.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| direction | Yes | ||
| max_frontier | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of behavioral disclosure. It details stopping conditions, return values (node_count, counts_by_kind, counts_by_model, frontier), frontier truncation at max_frontier, and cross_hierarchy grouping, providing comprehensive behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but each sentence adds value. It front-loads the purpose and logically describes behavior and return fields. Could be slightly more concise, but overall effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers tool behavior, parameters, and return values well. It explains the frontier structure and cross_hierarchy grouping. Lacks examples or exact formatting for counts, but for a specialized tool it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds meaning for direction (fanin|fanout) and max_frontier (<=200, caps lists), and implies path is a term/net. While not fully structured, it provides critical context beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool traces the combinational fanin/fanout cone of a term/net via naja's LogicCone, specifying direction and behavior (crosses hierarchy, stops at flops/ports/blackboxes). It distinguishes from siblings like get_drivers/get_loads by focusing on cones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for tracing combinational cones but does not explicitly state when to use this tool versus alternatives or provide conditions for use. No comparative guidance with sibling tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.8findget_driversget_hierarchyget_intentget_loadsget_module_cardget_sourceget_statsload_intentload_libertyload_primitivesload_snapshotload_systemverilogload_verilogquery_pythonreset_universeresolvesave_snapshotstatustrace_coneEach tool has a clearly distinct purpose: find searches globally, get_drivers and get_loads are mirror fanin/fanout queries, get_hierarchy shows module tree, get_intent extracts source-level intent, get_source provides source lines, get_stats aggregates counts, resolve resolves paths, trace_cone traces logic cones, and load/save/manage tools handle session state. No overlapping functionality.
Naming conventions are mixed: most tools use 'verb_noun' with underscores (e.g., get_drivers, load_systemverilog), but 'find' and 'status' lack underscores, and 'query_python' uses a language name. The pattern is not fully consistent, though individual names are still readable.
With 20 tools, the server provides a comprehensive set for hardware design analysis (loading, querying, saving, management). The count is slightly above the typical 3-15 range but justified given the domain's complexity; each tool serves a necessary role.
The tool surface covers loading multiple formats (SystemVerilog, Verilog, Liberty, snapshots), querying hierarchy, drivers, loads, intent, source, and stats, plus management (reset, save, load, status). Missing write/modify operations, but that aligns with an analysis-focused scope. The Python escape hatch fills gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for generating rough-draft project plans from natural-language prompts.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/najaeda/naja-scope'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
