# The describe ladder

**🟠 Advanced · Lesson 14**

THE DESCRIBE LADDER - why the read surface is not one fat describe() per thing, and why that shape is aimed at agents.

Look at what ViewSpell offers for a single spell:

describe_spell_brief(...) the smallest useful answer describe_spell(...) the normal record describe_spell_detail(...) the long form describe_spell_payload(...) the raw payload

...and then NINE per-facet verbs that hand you exactly one slice:

describe_spell_identity describe_spell_source describe_spell_origin describe_spell_binding describe_spell_index describe_spell_resolution describe_spell_metadata describe_spell_research describe_spell_class_profile

ViewConduit is built the same way - brief / describe / topology / inventory / relationships / crosswalk, plus root and policy filters.

THIS IS A CONTEXT BUDGET CONTROL.

A human reading one spell does not care whether the payload is 400 bytes or 40,000. An agent with a finite context window cares enormously. The ladder lets a caller enumerate 400 spells at BRIEF, decide which three matter, and pay full price for only those three.

A single fat describe() forces the opposite trade: either it is thin and you cannot answer detailed questions, or it is fat and surveying anything is unaffordable. The ladder refuses that choice.

THE CHEAP RUNG IS ALWAYS list_* list_spells / list_conduits / list_root_conduits Names and ids first. Descriptions only for what survives the filter.

A NOTE ON THIS LESSON'S WORLD ViewSpell and ViewConduit are FRAME-SCOPED (lesson 13), and a freshly opened rift is contracted to no frames - so this lesson maps the ladder off the EXPORTED TYPES rather than off instances. That is not a workaround: THE LADDER IS A PROPERTY OF THE CLASS. You do not need a populated world to see the shape of the surface you will be paying for, which is exactly the point of surveying before you commit.

The HOST-SCOPED view (get_view_multiframe) needs no frame, so the cheapest rung of all really is callable before you have assigned anything - and this lesson proves that too.

## Before you run

Use the [Advanced guide](../../advanced/index.md) for prerequisite concepts. Run from a checkout with Melder installed and Python 3.14 free-threading selected. The collection download includes the level's local helper modules.

## Run the saved script

```bash
python UX_and_AIX_experiences/03_advanced/14_the_describe_ladder.py
```

```powershell
py -3.14t UX_and_AIX_experiences/03_advanced/14_the_describe_ladder.py
```

{download}`Download this collection <../../downloads/advanced-examples.zip>` · [Source on GitHub](https://github.com/Synaptic724/melder/blob/0895ce795453cd87e35d70665957b4e89aad3317/UX_and_AIX_experiences/03_advanced/14_the_describe_ladder.py)

## Public surface

md.ViewSpell, md.ViewConduit - the describe ladder,
                   list_* enumeration, empty-world coherence

## Code

```{literalinclude} ../../downloads/03_advanced/14_the_describe_ladder.py
:language: python
:linenos:
```

## Check the outcome

The script contains its own assertions or demonstrated refusal paths. Run it to evaluate those checks against your installed version. The code above is taken directly from the saved file; no run output is invented here.

[More advanced examples](index.md) · [Level guide](../../advanced/index.md)

## Related guides

- [Viewer navigation and the describe ladder](../../advanced/viewers.md)

## API contracts

- [ViewConduit](../../reference/api/inspection/viewconduit.md)
- [ViewSpell](../../reference/api/inspection/viewspell.md)