Feature: Define Tool and Parameter Descriptions in Code and Validate Them Before Runtime #114

Feature: Define Tool and Parameter Descriptions in Code and Validate Them Before Runtime

Problem

Today, tool descriptions are defined in YAML.

In practice, these descriptions are sometimes too short or not detailed enough for the LLM to clearly understand:

• What the tool does.
• When the tool should be used.
• What each parameter means.
• What value should be provided for each parameter.

This can lead to incorrect tool selection or incorrect argument generation by the LLM.

The description is also separated from the actual tool implementation, which makes it easier for the YAML definition and the code to become inconsistent.

Proposed Change

The tool implementation file should become the source of truth for the LLM-facing tool metadata.

When implementing a tool, the developer should be required to define:

• A meaningful description for the tool itself.
• A meaningful description for every exposed tool parameter.

For example:

@tool(
    description="""
    Retrieves customer information for a specific customer code.
    Use this tool when customer-related information is required.
    """
)
def get_customer(
    customer_code: Annotated[
        str,
        "The unique customer code used to identify the customer."
    ],
    include_inactive: Annotated[
        bool,
        "Whether inactive customers should be included in the result."
    ],
):
    ...

The exact annotation/API can follow Extra's existing implementation, but the important requirement is that the descriptions live directly next to the tool implementation.

Tool Discovery / Generation

During tool generation, Extra should inspect the actual tool source file.

It should:

1. Find the tool function.
2. Find all parameters exposed by that tool.
3. Extract the tool description.
4. Extract the description for each parameter.
5. Use this metadata to generate the final tool definition/schema exposed to the LLM.

Expected flow:

Tool source file
      ↓
Find tool function
      ↓
Find exposed parameters
      ↓
Extract tool description
      ↓
Extract parameter descriptions
      ↓
Validate metadata
      ↓
Generate tool schema
      ↓
Expose tool to the LLM

The generated tool schema should include both levels of description:

{
  "name": "get_customer",
  "description": "Retrieves customer information for a specific customer code.",
  "parameters": {
    "customer_code": {
      "type": "string",
      "description": "The unique customer code used to identify the customer."
    },
    "include_inactive": {
      "type": "boolean",
      "description": "Whether inactive customers should be included in the result."
    }
  }
}

Remove YAML as the Source of Truth

Tool descriptions should no longer need to be manually maintained in YAML.

The metadata should come from the tool implementation itself.

This keeps the LLM-facing contract close to the actual code and reduces the chance of stale, duplicated, or incomplete descriptions.

Validation

This requirement must be enforced during the existing Extra validation phase.

It should not fail for the first time during runtime or when the LLM tries to invoke the tool.

During extra validate, Extra should validate that:

• Every tool has a description.
• The tool description is not empty or whitespace-only.
• Every exposed tool parameter has a description.
• Parameter descriptions are not empty or whitespace-only.

If any metadata is missing, validation should fail immediately.

Example:

Tool validation failed for "get_customer":

- Tool description is missing.
- Parameter "customer_code" is missing a description.
- Parameter "include_inactive" has an empty description.

The validation message should be clear and actionable so the developer immediately knows:

• Which tool is invalid.
• Which parameter is invalid.
• What metadata needs to be added.

Important

This is not only documentation.

Tool descriptions and parameter descriptions are part of the contract provided to the LLM and directly affect:

• Tool selection.
• Tool understanding.
• Argument generation.
• Overall tool-calling reliability.

Therefore, incomplete tool metadata should be treated as an invalid tool definition.

Acceptance Criteria

• Tool descriptions are defined in the tool implementation file.
• Every exposed tool parameter has its own description.
• Tool generation finds the tool and its parameters directly from the tool source file.
• Tool descriptions are propagated to the generated tool definition.
• Parameter descriptions are propagated to the generated input schema.
• YAML is no longer the source of truth for tool descriptions.
• Missing tool descriptions fail validation.
• Missing parameter descriptions fail validation.
• Blank or whitespace-only descriptions fail validation.
• Validation happens during extra validate, before runtime.
• Validation errors clearly identify the tool and the exact invalid parameter.
• Missing metadata is never discovered for the first time when an agent or tool is executed.
• Tests cover valid tools, missing tool descriptions, missing parameter descriptions, blank descriptions, and multiple validation errors.