Do LLM tool parameters need descriptions?

Yes. The model fills each argument from the parameter's name, type, and description. Without a description it guesses the format, which produces malformed calls and retries. Describe every parameter with its format and a concrete example, and constrain closed sets with an enum.

Does the auditor check nested parameters?

Yes. It walks the whole parameter schema, including nested objects and array-item schemas, so an undescribed field deep inside a filter object is caught the same as a top-level one. The model has to fill those nested fields too.

Parameters with no description

A parameter with no description is one the model fills by guessing the format. Undescribed parameters are where malformed tool calls come from: the wrong date format, the wrong id, the wrong unit.

see_it · fix_it

The failure, then the fix

Each verdict below is the actual MCP & Agent Tool Auditor run on the snippet, not a description of one.

before

[
  {
    "name": "list_orders",
    "description": "List a customer's orders within a date range. Use this when the user asks to see past orders.",
    "input_schema": {
      "type": "object",
      "properties": { "customer_id": { "type": "string" }, "since": { "type": "string" }, "until": { "type": "string" } },
      "required": ["customer_id"]
    }
  }
]

Warns · auditor verdict3 of 3 parameters (including nested fields) have no description, in list_orders. An undescribed parameter is one the model fills by guessing the format, which is where malformed tool calls come from.

after

[
  {
    "name": "list_orders",
    "description": "List a customer's orders within a date range. Use this when the user asks to see past orders.",
    "input_schema": {
      "type": "object",
      "properties": {
        "customer_id": { "type": "string", "description": "The customer's UUID, e.g. 8f3a…" },
        "since": { "type": "string", "description": "Start of the range, ISO-8601 date like 2026-01-01" },
        "until": { "type": "string", "description": "End of the range, ISO-8601 date like 2026-01-31" }
      },
      "required": ["customer_id"]
    }
  }
]

Passes · auditor verdictMost parameters are described, so the model knows the shape and meaning of each value it has to supply.

fix · Give every parameter a description with its format and an example, e.g. "ISO-8601 date, like 2026-01-31". The model only knows what you tell it.

why_it_matters

The model only knows what you tell it. A parameter named 'date' with no description could be an ISO string, a Unix timestamp, or 'next Tuesday' as far as the model can tell, and it will guess, often differently each time. Every guess that doesn't match what the tool expects is a failed call, a retry, and wasted tokens. Give each parameter a description with its exact format and an example: 'ISO-8601 date, like 2026-01-31'.

This applies to nested fields too, not just the top level. A filter object three levels deep with undescribed members fails the same way. The auditor walks the whole parameter schema, including nested objects and array items, and flags when a meaningful share of the parameters across your tools carry no description.

"date": { "type": "string" }model guesses the formatstate the format and an example

more_failure_modes

Related ways tools break

Parameter schema

Schemas that don't mark anything required

Read it Tool selection

Descriptions that don't say when to use the tool

Read it

See all 6 failure modes, or read what tool calling is.

faq

Questions & answers

Do LLM tool parameters need descriptions?: Yes. The model fills each argument from the parameter's name, type, and description. Without a description it guesses the format, which produces malformed calls and retries. Describe every parameter with its format and a concrete example, and constrain closed sets with an enum.
Does the auditor check nested parameters?: Yes. It walks the whole parameter schema, including nested objects and array-item schemas, so an undescribed field deep inside a filter object is caught the same as a top-level one. The model has to fill those nested fields too.

Spotting one failure is easy. Hardening the whole agent is the work.

I review which tools the loop can reach autonomously, how you fence destructive calls behind confirmation, idempotency on the side effects, and the evals that catch a wrong tool call before users do. Book a call, or leave your email.

Book a call

Prefer proof first? See how this plays out in real case studies →