Split title from description in the JSON Schema instead of prefixing the label onto every description

Problem/Motivation

ContextDefinitionNormalizer::getDescription() builds every description as Label: Description, and the same label goes out as title. A member whose docblock says "Gets the title." is advertised as:

"title": {
  "type": "string",
  "title": "Title",
  "description": "Title: Gets the title."
}

The label appears three times: as the key, as title, and as a prefix on description. The comment above the code says why: most LLM clients only surface description, so the label is merged into it, and title duplicates it for consumers that render titles. That was a reasonable default, but it is a prompt-visible change to undo, and the normalizer comment defers it to a follow-up issue. This is that issue.

The prefix is a fixed cost on every input and output Tool API has ever emitted, and it is cheap to remove: the same information is already carried by title.

A second placement problem sits in the same method. A multiple definition puts the definition's description on items and gives the array itself "Array of <Label>":

"covers": {
  "type": "array",
  "title": "Covers",
  "description": "Array of Covers",
  "items": {
    "type": "object",
    "title": "Covers",
    "description": "Covers: The covers."
  }
}

The author's text describes the list, not one item, so it belongs on the array. The item schema should get nothing unless the item definition has its own description.

Proposed resolution

  • description carries the definition's description only. When a definition has no description, the key is omitted.
  • title keeps carrying the label.
  • For a multiple definition the description goes on the array, and items carries no description of its own.

This changes the prompt text of every tool, so it should land before 1.0.0 and be called out in the release notes.

Remaining tasks

  • Change ContextDefinitionNormalizer::getDescription() and the multiple branch of getNormalizationSchema().
  • Update the schema matrix expectations (#3583001 (closed)).
  • Check the documentation examples that show Label: description output.
Edited by drupalbot