Skip to main content
Glama

semver_snapshot

Idempotent

Extract a TypeScript project's public API surface as JSON without comparing versions, so you can inspect package exports before deciding a semver bump.

Instructions

Extract the public API surface of a TypeScript project as JSON, without comparing it to anything. Use it to see what a package exports; use semver_compare to decide a bump. The source can be a filesystem path, a git ref, or an npm spec, the same three forms semver_compare takes, with the same network and temp-directory behaviour. Returns {"entrypoints": {: {: }}}, with each symbol's full type shape in place of its kind when "detail" is set. Symbols stop at the "maxBytes" budget, and an "omitted" field then gives the number left out and the total. A source whose surface comes back empty is reported as an analysis_failed error, not as an empty result; pass "entry" to point at the declaration file.

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": "semver_snapshot"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNoProject source: a filesystem path, a git ref, or an npm spec such as "lodash@4.17.21". Defaults to current directory..
entryNoEntry file relative to project root (e.g. "src/index.ts"). Pass an array or a comma-separated string for a package with several entry points.
detailNoInclude each symbol's full type shape instead of just its kind. A shape runs a median of about 370 bytes and a wide interface tens of kilobytes, against about 35 for a name and a kind, so a large package will hit the byte budget after a few dozen symbols.
pathAsNoForce "path" to be treated as a filesystem path, a git ref, or an npm spec. "ref" is an accepted spelling of "git". Only needed when auto-detection would read the input as the wrong kind.
maxBytesNoByte budget for the symbols in the response (default 40000). Symbols are included while it lasts, and an "omitted" field then reports how many were left out along with the total. No symbol is exempt: under "detail" a single wide interface can cost tens of kilobytes, so a budget smaller than that returns no symbols and says so rather than overshooting. Only the entrypoint keys and the "omitted" field sit outside the budget, a few hundred bytes.
installDepsNoInstall dependencies before analysis. In a local path with no node_modules this runs "npm install --ignore-scripts" in that directory, and adds @types/node there if it is missing. Only a local path needs it: a git ref is always installed in its temp copy.

Output Schema

NameRequiredDescriptionDefault
omittedNo
entrypointsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.17.0
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "entrypoints": {
      +      "additionalProperties": {
      +        "type": "object"
      +      },
      +      "type": "object"
      +    },
      +    "omitted": {
      +      "properties": {
      +        "count": {
      +          "type": "integer"
      +        },
      +        "note": {
      +          "type": "string"
      +        },
      +        "total": {
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "count",
      +        "total",
      +        "note"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "entrypoints"
      +  ],
      +  "type": "object"
      +}
  2. Changed1 schema field changedv0.15.2
    • changedInput schema / properties / installDeps / description
      Previous value: -"Install dependencies before analysis"New value: +"Install dependencies before analysis. In a local path with no node_modules this runs \"npm install --ignore-scripts\" in that directory, and adds @types/node there if it is missing. Only a local path needs it: a git ref is always installed in its temp copy."
  3. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations it discloses non-obvious behaviour: three accepted source forms with shared network and temp-directory handling, dependency installation side effects ('npm install --ignore-scripts' in the target directory), byte-budget truncation with an 'omitted' count, and the fact that an empty surface surfaces as analysis_failed rather than an empty result. The install side effect is consistent with readOnlyHint=false and openWorldHint=true.

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?

Front-loaded with purpose and the sibling routing rule, then return shape, then failure/budget semantics; nearly every sentence carries information. Minor redundancy from repeating the 'omitted' budget mechanics already spelled out in the schema.

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?

For a read-only-but-filesystem-touching tool with six optional parameters, it covers source forms, installation, output shape, truncation, and the failure mode, which is everything an agent needs before calling. The return-shape sentence is arguably redundant against the output schema but costs little and pre-empts misinterpretation of truncation.

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 operational meaning the schema lacks: cost tradeoffs for 'detail' (median ~370 bytes vs ~35), what happens when maxBytes is smaller than a single symbol, and the 'entry' workaround for declaration files. It partly restates the 'omitted'/budget text already present in the maxBytes schema entry.

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 ('Extract the public API surface of a TypeScript project as JSON') and immediately negates the sibling's behaviour ('without comparing it to anything'), so the agent can distinguish it from semver_compare without reading either 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?

Gives an explicit positive case ('use it to see what a package exports') and an explicit alternative with its selecting condition ('use semver_compare to decide a bump'), plus a troubleshooting rule ('pass "entry" to point at the declaration file').

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