Skip to main content
Glama

List expiring ENS names

list_expiring_names
Read-onlyIdempotent

List ENS names that expire soon, soonest first, e.g. 'Which of nick.eth's names expire in the next 30 days?' or 'What names under ens.eth expire this month?'. Give address for one address's names (owned, managed or held through roles); then up to limit names come back in one answer, without a cursor. includeGrace adds names that already expired but are in their grace period, when they can still be renewed. Results come from an indexer and can lag the chain by a few blocks.

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

Input Schema

NameRequiredDescriptionDefault
limitNoItems per page, 1 to 100. Default: 25
cursorNocursor from the previous page, to read the next one
parentNoOnly direct subnames of this name; with no address only
addressNoEthereum address (0x…) or an ENS name resolving to one, e.g. nick.eth
namespaceNoens (default), or basenames for *.base.eth names on Base
withinDaysNoDays ahead to look, 1 to 3650. Default: 30
includeGraceNo

Output Schema

NameRequiredDescriptionDefault
toYesEnd of the window searched
asOfNoChain time the indexer's answer reflects
fromYesStart of the window searched
itemsYes
totalNo
cursorNoPass back as cursor for the next page; absent on the last page
partialNoWhy the answer may be incomplete

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior4/5

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses real behavior an agent could not infer: results come from an indexer and "can lag the chain by a few blocks," and in address mode results return "without a cursor" up to the limit. It does not cover rate limits, permission requirements, or why cursor exists in the schema at all, leaving a small ambiguity with the address-mode statement.

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 expiry scope and ordering are front-loaded, followed by examples and then parameter behavior, which is a sensible order. The address/cursor sentence is slightly convoluted ("then up to limit names come back in one answer, without a cursor"), but there is no filler.

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 seven optional parameters, an output schema present, and annotations covering safety, the description covers the modes an agent must choose between (all names vs. one address vs. one parent) and the staleness caveat. The only real gap is the unresolved relationship between the cursor parameter and the stated cursorless address mode.

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 already 86%, so the baseline is 3; the description earns an extra point by clarifying that address covers names "owned, managed or held through roles" and by explaining includeGrace (which has no schema description) in terms of renewability. It adds nothing beyond the schema for parent, namespace, or withinDays, though those are already documented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/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 ("List ENS names that expire soon") plus the ordering ("soonest first"), which immediately tells an agent this is an expiry-scoped listing rather than a general name lookup. It does not name the neighbouring list_names_for_address or search_names tools, so the differentiation is implied by scope rather than made explicit.

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?

Two concrete sample questions plus the instruction "Give address for one address's names (owned, managed or held through roles)" make the address-mode trigger clear, and "includeGrace adds names that already expired but are in their grace period" explains that toggle's purpose. What is missing is any explicit when-not guidance or a named alternative for cases where the agent wants non-expiring names.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.