Azure / Azure/azure-rest-api-specs

[BUG] Foundry Responses: OpenAI.NamespaceToolParam.description adds minLength: 1 not present upstream, rejecting valid requests

Open Beginner friendly
#45,388 0 comments 3 reactions 0 assignees View on GitHub
customer-reported data-plane Foundry question Service Attention
Dominant language
TypeSpec
Stars
3.1k
Forks
5.9k
Avg merge
2d 22h
Merged PRs (30d)
444

Description

### API Spec link

https://github.com/Azure/azure-rest-api-specs/blob/main/specification/ai-foundry/data-plane/Foundry/openapi3/v1/microsoft-foundry-openapi3.yaml#L62594-L62597

### API Spec version

`v1` (`openapi3/v1/microsoft-foundry-openapi3.yaml`, component `OpenAI.NamespaceToolParam`)

### Describe the bug

The Foundry spec adds `minLength: 1` to `OpenAI.NamespaceToolParam.description`. The upstream OpenAI Responses schema it is derived from does not carry that constraint, and the live Foundry service enforces the added constraint, so requests that are valid against OpenAI's published schema are rejected with HTTP 400.

Foundry, `openapi3/v1/microsoft-foundry-openapi3.yaml` line 62594:

```yaml
description:
type: string
minLength: 1
description: A description of the namespace shown to the model.
```

Upstream, [openai/openai-openapi](https://github.com/openai/openai-openapi/blob/main/openapi.yaml), component `NamespaceToolParam` (and identically `BetaNamespaceToolParam`):

```yaml
description:
type: string
description: A description of the namespace shown to the model.
```

The two definitions are otherwise identical: same `required` list (`type`, `name`, `description`, `tools`), same `minLength: 1` on `name`, same `minItems: 1` on `tools`, same doc strings verbatim. The only difference is the added constraint on `description`.

Worth noting the contrast inside the same object upstream: `name` carries an explicit `minLength: 1` while `description` does not. That reads as a deliberate distinction rather than an omission.

### Expected behavior

A `namespace` tool with `"description": ""` is accepted, matching the upstream schema. The key itself remains required, since `description` is in the `required` list in both specs.

### Actual behavior

```json
{
"error": {
"message": "Invalid 'input[0].tools[0].description': empty string. Expected a string with minimum length 1, but got an empty string instead.",
"type": "invalid_request_error",
"param": "input[0].tools[0].description",
"code": "empty_string"
}
}
```

### Reproduction Steps

Three requests against a Foundry Responses deployment (`gpt-5.6-sol`, East US 2), identical except for `input[0].tools[0].description`:

| `description` | Result |
| --- | --- |
| `""` | 400 `empty_string` |
| key omitted | 400 `missing_required_parameter` |
| `"Default Codex tools."` | 200 OK |

The middle row is correct and matches upstream, since `description` is required in both specs. The first row is the divergence. The third row confirms Foundry otherwise implements the `additional_tools` and `namespace` surface correctly, so this is narrowly a validation difference on one field rather than a missing feature.

```bash
curl -s https://.services.ai.azure.com/openai/v1/responses \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
"model": "gpt-5.6-sol",
"input": [
{"type": "additional_tools", "role": "developer", "tools": [
{"type": "namespace", "name": "functions", "description": "", "tools": [
{"type": "function", "name": "noop", "description": "does nothing",
"parameters": {"type": "object", "properties": {}, "additionalProperties": false},
"strict": true}
]}
]},
{"type": "message", "role": "user", "content": [{"type": "input_text", "text": "say OK"}]}
],
"stream": false
}'
```

### Impact

This currently breaks the OpenAI Codex CLI against every Foundry-backed Responses provider: openai/codex#37380. Codex 0.147.0 serializes its default `functions` namespace with an empty description, so every request fails before any model output. It still reproduces on 0.148.0-alpha.6.

Codex has a one-line fix pending on their side, and sending a meaningful description is better regardless. Filing here because the divergence is independent of that client: any caller that emits a spec-valid empty description hits the same wall, and only on Foundry.

### Ask

Either drop `minLength: 1` from `OpenAI.NamespaceToolParam.description` so the schema and service match upstream, or, if the stricter validation is intentional, document the divergence so client authors targeting both endpoints know to avoid empty descriptions.

Contributor guide

Open the contributing guide

Research direction

Start with specification/ai-foundry/data-plane/Foundry/openapi3/v1/microsoft-foundry-openapi3.yaml around lines 62594-62597 and compare OpenAI.NamespaceToolParam with the upstream schema. Verify the empty-description behavior and determine whether the constraint should be removed or the divergence documented; done means the chosen behavior is reflected consistently in the spec and service guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.