Skip to main content
Glama
keplertech

naja-scope

by keplertech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

trace_cone

Read-onlyIdempotent

Trace combinational fanin or fanout logic reachability across hierarchy, stopping at flops, ports, and black boxes. Returns node counts and frontier details.

Instructions

Trace the combinational fanin/fanout cone of a term/net via naja's LogicCone. Use this for transitive logic reachability; use get_drivers or get_loads for only immediate endpoints. 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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYesExact hierarchical path to the cone's root term or net.
directionYesTraverse upstream fanin or downstream fanout logic.
max_frontierNoMaximum listed endpoints per frontier kind; clamped to 1..200.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.9
    • addedInput schema / properties / direction / description
      Added value: +"Traverse upstream fanin or downstream fanout logic."
    • addedInput schema / properties / direction / enum
      Added value: +[
+  "fanin",
+  "fanout"
+]
    • addedInput schema / properties / max_frontier / description
      Added value: +"Maximum listed endpoints per frontier kind; clamped to 1..200."
    • addedInput schema / properties / path / description
      Added value: +"Exact hierarchical path to the cone's root term or net."
  2. First observedv0.1.8

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds real traversal semantics: the cone crosses hierarchy and combinatorial arcs and always terminates at flops, top ports, and opaque black-box cells. This is behavior beyond the annotations, though much of the rest of the text shifts toward return format.

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?

Purpose and the sibling distinction are front-loaded, and most sentences carry useful information. It runs slightly long, with return-shape detail that could be tightened, but nothing is gratuitous.

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?

With no output schema, the description carries the return-value burden and does so thoroughly (node_count, counts_by_kind/model, frontier shape, truncation marker, cross_hierarchy/outside_root_subtree semantics). Combined with full param coverage and rich annotations, an agent has everything needed to call and interpret it.

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%, so both direction and max_frontier are already documented (including the 1..200 clamp and default 50). The description restates direction and the <=200 cap but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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?

States a specific verb (Trace) and resource (combinational fanin/fanout cone of a term/net) with clear scope, and names get_drivers/get_loads as the immediate-endpoint alternatives, so an agent can distinguish it from siblings without opening any schema.

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?

Explicitly says when to use it (transitive logic reachability) versus the alternatives (get_drivers/get_loads for immediate endpoints only), which is exactly the selection guidance an agent needs.

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