files.read_outline

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

Annotations are empty, so the description carries the full burden, and it delivers: 'Read-only; no side effects, auth, or rate limits' covers the safety/permission profile. It also adds the counterintuitive empty-outline behavior ('file has no markdown headings — it may still have content'), preventing an agent from misreading an empty result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four compact sentences: purpose, safety, usage-as-probe, and empty-outline fallback. Every sentence carries a distinct, necessary fact, and the most important information is front-loaded in the first clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the untouched return shape is named inline (level, text, line, byteStart, byteEnd) and the empty case is massively covered. The only gap is error handling for invalid file ids, but for a single-parameter, side-effect-free probe the description is substantially complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter file_id has 100% schema description coverage ('File ID'), so the description adds nothing meaningfully new about the parameter itself. The text references the logical file and headings, but this is the baseline-3 for schemas that already fully document parameters.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Return a flat list of markdown headings for one file (level, text, line, byteStart, byteEnd)', which names the verb, resource, and output shape. It clearly distinguishes from siblings like files.read (full body) and files.list (multiple files) without needing to open the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use as a cheap probe before files.read({ id, section }) or files.update(...)' names the exact sibling alternates and the cost rationale. The empty-outline note also tells the agent to fall back to files.read in full or with lines, making the when-to-use and when-to-bail behavior explicit.

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