Skip to main content
Glama

Where Used

where_used
Read-only

Traverse the lockfile dependency graph to report every parent that consumes an item, revealing the full blast radius for impact analysis. Optionally surface immediate direct parents separately.

Instructions

Where-used / impact analysis (issue #142, C3; MULTI_AGENT.md §9): traverse the lockfile depends_on graph and report every parent that CONSUMES an item — the blast radius, so exactly those parents re-dispatch when the item changes. The lockfile records edges consumer -> consumed (lid depends_on housing); where-used is the reverse reachability of the item (everything that reaches it).

lockfile: path to the lockfile (the JSON assembly_lock wrote). item: the item / component id to query. direct: if true, also surface only the immediate mates separately.

Returns {item, where_used (the full transitive blast radius), direct (the §9 immediate-neighbour layer)} — an unknown item fails loudly, never a silent empty set.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "lockfile": "<lockfile>",
      "item": "<item>"
    },
    "name": "where_used"
  }
}

Input Schema

NameRequiredDescriptionDefault
itemYes
directNo
lockfileYes
workspaceNoRun this call in this named workspace

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds real behavioral context beyond that: the return shape {item, where_used, direct}, the guarantee that an unknown item fails loudly rather than returning a silent empty set, and that the lockfile is the JSON assembly_lock wrote. It stops short of noting cost or traversal limits on large graphs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Core semantics are front-loaded, but internal scaffolding like '(issue #142, C3; MULTI_AGENT.md §9)' is noise for an agent and consumes prime space. The `direct` sentence is worded in a way that costs a re-read.

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

Completeness4/5

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

With no output schema, the description correctly documents the return value and the failure mode, and it explains the graph orientation an agent needs to interpret results. Remaining gap is the undocumented `workspace` parameter and any guidance on lockfile freshness relative to assembly_lock.

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 only 25% (just `workspace`), so the description must carry the load, and it does for three of four params: `lockfile` (path to the JSON assembly_lock wrote), `item` (component id to query), and `direct` (surface the immediate mates separately). The `direct` phrasing 'also surface only the immediate mates separately' is internally awkward and could confuse whether it narrows or supplements the result; `workspace` is left to the shared convention.

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 and resource — traverse the lockfile `depends_on` graph and report every parent that consumes an item — and pins the direction of traversal (edges are consumer -> consumed; where-used is the reverse reachability). It distinguishes itself from the graph-writing sibling by naming assembly_lock as the producer of the lockfile, so an agent can tell what this reads and why.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for use: blast-radius / impact analysis, so exactly those parents re-dispatch when the item changes. That is an actionable when-to-use condition, but it never names an alternative (e.g. change_impact, bom_extract, assembly_lock_check) or states when-not to reach for this one.

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