Skip to main content
Glama

Code that still needs a plain-English description

graph_pending

Lists undocumented or changed functions and classes with source, callers, callees, and tests so you can write descriptions or explain logic changes.

Instructions

Functions and classes that have no plain-English description yet (or whose code changed since it was written), with their source, callers and callees. Write the descriptions yourself and save them with graph_describe; nothing is sent to any model by this tool. With changes=true, lists changed code whose logic changed (not code proven to keep the same logic) to explain instead, each with its old and new code, proven facts, the tests that reach it and its callers (code proven to call it within 2 steps, with what each does today), and writes .skylos/graph/changes.json for the viewer; explain each change and, in impact, how it changes each listed caller that behaves differently. Use change_map first to see what to read. Returns JSON. Local.

Works without SKYLOS_API_KEY and has no daily limit: it reads the repository on this machine and sends nothing to Skylos Cloud.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "graph_pending"
  }
}

Input Schema

NameRequiredDescriptionDefault
baseNoWith changes=true: compare with the merge base of this git ref, e.g. origin/main. Default HEAD: only uncommitted changes.HEAD
pathNoProject directory. A relative path resolves against the MCP server's working directory..
limitNoHow many items, 1-50
changesNoList changes to explain instead of code to describe

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv5.6.0

TDQS

A4.6/5.0
Behavior5/5

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

The annotations declare readOnlyHint=false and no destruction, and the description explains why by disclosing the concrete side effect: with changes=true it writes .skylos/graph/changes.json for the viewer. It also states that nothing is sent to any model, that it works without SKYLOS_API_KEY, and that there is no daily limit and no cloud traffic, which is behavior an agent cannot derive from the annotations or schema.

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 definition is front-loaded: the default behavior comes first, then the changes=true variant, then the environment and credential facts. Every clause carries information, but the changes=true sentence is a long run-on with stacked parentheticals that slows parsing, and the same content could be broken into bullets for faster scanning.

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?

It covers all the elements an agent needs for a tool with two modes, four optional parameters, a JSON output schema and annotations: what is returned, which mode to use when, the write side effect, and the local and credential-free nature. With the output schema handling return shape, nothing material is left implicit.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning on top: it explains what changes=true does, and that base compares against the merge base of a git ref and defaults to uncommitted changes under HEAD. It also characterizes the shape of what each mode returns (old and new code, proven facts, tests, callers within 2 steps). The limit and path parameters are left entirely to the schema.

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 and resource: it lists functions and classes lacking plain-English descriptions, plus their source, callers and callees. It also distinguishes the two modes (default pending-list vs. changes=true) and names the siblings it hands off to, graph_describe and change_map, so an agent can tell it apart from those without opening their schemas.

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?

It gives concrete workflow guidance: write descriptions yourself and save them with graph_describe, and use change_map first to see what to read. The changes=true condition ('lists changed code whose logic changed ... to explain instead') is spelled out. What is missing is an explicit statement of when *not* to use it, e.g. that it is not a search tool and that graph_find or graph_show would be used to locate specific symbols instead.

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