> ## Documentation Index
> Fetch the complete documentation index at: https://agentharnesses.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Optimizing Descriptions

> How to write descriptions that help agents navigate to the right content at the right time.

# Optimizing Descriptions

Descriptions are short but load-bearing. They are the primary signal an agent uses during the **Discovery** phase to decide which directories and files are relevant to a given task. A poor description means content gets ignored or loaded unnecessarily.

## The description field

Every `HARNESS.md` and every routing file has a `description` field in its frontmatter. Individual markdown files should include one too. Write this field as if you're answering the question: *"When should an agent look here?"*

```yaml theme={null}
---
description: Condense a piece of text into a concise summary preserving the main argument.
---
```

Not:

```yaml theme={null}
---
description: Summarization skill.
---
```

***

## Rules for good descriptions

### Be specific about the trigger

A description should make it obvious when this skill, directory, or document applies. Include the input type, the output type, or the situation.

| Weak                 | Strong                                                            |
| -------------------- | ----------------------------------------------------------------- |
| "Handles blog posts" | "Draft or edit a long-form blog article from an outline or brief" |
| "Database stuff"     | "Read from and write to the PostgreSQL product database"          |
| "Style information"  | "Typography, tone, and formatting rules for all marketing output" |

### Use verbs for actions, nouns for context

Skills and capabilities are actions; reference material is knowledge. This distinction helps agents classify what they're loading.

* Capability: *"Generate a social media caption from a product description"*
* Context: *"Brand voice guidelines and prohibited language list"*

### Don't describe implementation details

The description is for relevance matching, not for explaining how something works. Keep implementation detail in the body.

| Too much detail                                                                                  | Right level                                                                   |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| "Uses Python script to call the OpenAI images API with a 1024x1024 resolution and returns a URL" | "Generate an image prompt and produce a visual asset from a text description" |

### Match the vocabulary users will use

Agents compare task descriptions against content descriptions. If your users say "summarize this" and your description says "condense and abridge", there's a mismatch. Use the words your users reach for naturally.

***

## Descriptions in HARNESS.md body

Inside the `HARNESS.md` body, you list top-level directories with inline descriptions. These should be even shorter — one clause is ideal — because the agent is scanning a list, not reading a document.

```markdown theme={null}
- `tools/` — capabilities for querying databases and processing files (see TOOLS.md)
- `data/` — schemas, data quality notes, and field definitions (see DATA.md)
- `outputs/` — skills for generating charts, tables, and reports (see OUTPUTS.md)
```

Each entry should be self-contained: a reader (or agent) who has never seen the harness should immediately understand what that directory is for.

***

## Testing descriptions

The practical test for a description is to give it to a colleague (or the agent itself) and ask: "Based only on this description, would you know when to look here?" If the answer is "it depends" or "I'm not sure", the description needs work.

See [Evaluating Harnesses](/harness-creation/evaluating-harnesses) for a systematic approach to testing description quality.