outline

Use outline when you know file paths and need their structural API or document organization without reading full bodies.

Use when

You need declarations, signatures, hierarchy, fields, methods, or imports.
You need headings and sections from a document.
You resolved a dependency symbol with jump and want that file's complete API; outline accepts absolute dependency-source paths.

Do not use when

You do not know the file; discover it with grep_definition.
You need implementation text; use extract with a returned handle.

Request

{"files":["/workspace/project/src/lib.rs","/workspace/project/src/api.rs"],"workspace_root":"/workspace/project"}

Parameters

Field	Required	Default / bounds
`files`	yes	One or more paths; `file_paths` is accepted as an alias.
`workspace_root`	no	Only needed when multiple workspaces are active.

Each file's structural outline: declarations, signatures, types, hierarchy, and imports for source; headings and sections for documents. Every symbol carries a handle with its available views and their line counts. If the outline answers the question, avoid a costly body read. Otherwise pass only relevant handles to extract.

Example

Real output, condensed — outlining a 2,261-line file from the Context Engine workspace:

saved: 85.4 KB -> 4.5 KB (95% fewer bytes)

# context-engine-core/src/infrastructure/lsp/process_manager.rs (2261L)
- #[derive(Debug)] pub struct LspProcessHandle { ... } ["1000t003" full 202L | code 17L | docs 185L]
  - pub process_id: u32 ["1000t000" full 2L | code 1L | docs 1L]
  - process_handle: Option<tokio::process::Child> ["1000t002" full 10L | code 1L | docs 9L]
- impl LspProcessHandle { ... } ["1000t00f" full 509L | code 509L]
  - pub fn extract_streams( &mut self, ) -> Result<(ChildStdin, ChildStdout, ChildStderr), StreamExtractionError> { ... } ["1000t006" full 53L | code 13L | docs 40L]
  - pub async fn terminate(&mut self) -> Result<()> { ... } ["1000t00b" full 124L | code 48L | docs 76L]
- #[async_trait::async_trait] pub trait ProcessManager: Send + Sync { ... } ["1000t00w" full 1437L | code 1118L | docs 319L]
  - async fn spawn_lsp_process( &self, config: &LspExecutionConfig, cancellation_token: CancellationToken, ) -> ... ; ["1000t00n" full 39L | code 5L | docs 34L]
  ... (24 more symbols)

The complete API of the file for 4.5 KB. The price tags show terminate is 48 lines of code but 76 lines of documentation, so the follow-up extract requests exactly the view the task needs.

Common mistakes

Passing a directory instead of a file path.
Reading full implementations when the outline is sufficient.
Using a dependency path without first resolving a visible dependency symbol with jump.

extract reads selected views from the returned handles.
grep_definition discovers definitions when you do not know the file.
jump resolves a dependency symbol to a source path you can then outline.
line_context starts from a line number instead of a file's structure.