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

Annotations are minimal (readOnlyHint false, idempotentHint false, destructiveHint false), so the description carries most of the burden. It adds genuinely useful behavioral context beyond annotations: the refusal field populated when the model declines, finish_reason values, nullability of usage tokens, and an error-handling note explaining that 'invalid request' usually means an unsupported parameter for that model. No contradiction with annotations.

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?

The description is long but remarkably well structured: purpose, usage, args, returns, examples, error handling, with the most decision-relevant information front-loaded in the first two sentences. The Args and Returns blocks partially duplicate the 100%-covered schema and the output schema, which costs some efficiency, but every unique section (examples, error handling) earns its place.

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?

For a 7-parameter tool with an output schema, the description covers all essentials: purpose, when to use and not use, parameter defaults, full return shape including edge cases (refusal, null usage), and the most common failure mode. Minor gaps remain — no mention of auth prerequisites or rate limits — but those are typically server-side concerns for an MCP wrapper.

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?

Schema description coverage is 100%, so the baseline is 3. The Args section essentially mirrors the schema's constraints (ranges, defaults, max items) without adding new semantic meaning; the schema's response_format description is actually richer than the description's terse version. The description adds no parameter insight beyond what structured data already provides.

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 first sentence names a specific verb and resource: send an explicit list of chat messages through the Chat Completions API. It immediately distinguishes itself from the sibling openai_generate_text ('For new single-prompt generations prefer openai_generate_text'), so an agent can tell them apart without opening either 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?

The description gives explicit when-to-use conditions (holding structured conversation history, needing verbatim replay, needing stop sequences), explicit when-not-to-use conditions (chaining stored responses), and names the alternative tool in each case. Nothing is left to inference.

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

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

The description discloses key behavioral traits: vectors are written to a JSON file by default, only the path and metadata are returned by default, inline return is limited to 5 texts, and dimensions are only supported by text-embedding-3 models. It also explains likely error messages and how to handle them, which goes well beyond the annotations.

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?

The description is well-structured with clear sections (summary, args, returns, examples, error handling) and front-loads the most important behavior. It is somewhat long and repeats some schema information in the Args list, but every section earns its place given the tool's complexity.

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?

For a 6-parameter tool with output-schema support, the description is complete: it covers the return JSON shape, the written file shape, default output behavior, parameter constraints, example use cases, and error scenarios. An agent has everything needed to select and invoke the tool correctly.

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?

Schema description coverage is 100%, so the baseline is 3. The description adds practical meaning beyond the schema: it explains why the default avoids inline vectors (a single vector holds up to 3072 floats), clarifies the max 5 texts for return_vectors, and connects the dimensions parameter to model compatibility. Some redundancy with the schema remains.

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 a clear, specific action ('Turn texts into embedding vectors') and names the intended applications (semantic search, clustering, deduplication). It also differentiates from the sibling openai_generate_text by explicitly saying when not to use this tool.

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?

The description gives concrete 'Use when' scenarios, such as building a semantic index or comparing two sentences directly, and an explicit 'Don't use when' case pointing to openai_generate_text. This makes tool selection unambiguous.

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

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

The description adds substantial context beyond the annotations (readOnlyHint=false, openWorldHint=true): files are read only from OPENAI_MCP_ALLOWED_DIRS, results are written back to disk, and an Error Handling section tells agents how to interpret 'File not found' versus permission failures. These details are actionable and not derivable from the annotations alone. No contradiction exists — the described file writes align with readOnlyHint=false.

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?

The description is lengthy but well-organized with clear section headers (Args, Returns, Examples, Error Handling) and a front-loaded purpose sentence. The Args and Returns blocks partly duplicate the schema and output schema, which is mild redundancy, but the Examples and Error Handling sections earn their space since they encode behavior not present in structured data.

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?

For an 8-parameter tool with file I/O, the description covers purpose, parameter meanings, filesystem constraints, failure modes, and usage examples thoroughly. The remaining gap is minor: it never states what happens when output_dir is omitted (the default output location), and the 'Don't use when' guidance covers only one sibling despite several related ones.

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?

Schema description coverage is 100%, so the baseline is 3. The Arg list in the description largely restates what the schema already documents (ranges, defaults, enum values) rather than adding new semantic depth; a few phrases like 'absolute paths to source images' reinforce but do not extend the schema text.

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 opening sentence states a specific verb phrase ('Edit or extend existing images according to a text instruction, optionally restricted to a masked region') that clearly identifies the resource (existing images) and the operation. It differentiates from the sibling openai_generate_image by explicitly calling out that creating from scratch is a different tool.

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?

The description provides concrete 'Use when' scenarios with realistic examples ('Replace the sky in photo.png with a sunset', 'combining several product shots into one scene') and an explicit 'Don't use when' with the named alternative (openai_generate_image). This is exactly the when/when-not/alternatives guidance the dimension asks for.

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

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

Annotations declare readOnlyHint=false, so the write behavior is expected, but the description adds substantial context beyond that: images 'are never returned inline — the tool saves each file and reports its absolute path', the rationale ('agent's context stays small'), environment-variable defaults, and a dedicated Error Handling section explaining what specific error strings mean (allowed-dir violations, unsupported size/quality combinations). No contradiction with annotations.

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?

The most important behavioral fact (saves to disk, never inline) is front-loaded in the first sentence. The remaining sections — Args, Returns, Examples, Error Handling — are each clearly headed and earn their place: the arg list is a fast reference, examples give actionable usage, and error strings turn failures into diagnosable conditions. No filler.

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?

For a 9-parameter tool with an output schema and annotations, this description is complete: it explains the core behavior, the return shape (paths, byte counts, revised_prompt semantics), the allowed environment constraints, when not to use it, and how to interpret common failures. Nothing an agent needs to invoke it correctly is missing.

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?

Schema coverage is 100%, so baseline is 3, but the description adds real value: it flags the cross-parameter constraint that 'transparent' requires png/webp output, documents env-var defaults for model and output_dir, and ties size/quality to model-specific rejection in the error section. It consolidates all 9 params into a scan-friendly list with constraints, going slightly beyond the schema's per-parameter descriptions.

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 a specific verb-resource pair ('Create one or more images from a text prompt') plus the distinguishing behavior 'write them to disk'. It explicitly contrasts itself with openai_edit_image in the examples, so an agent can tell this tool apart from its closest sibling without inspecting schemas.

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?

Provides explicit 'Use when' examples with concrete prompt transformations, a conditional example (transparent sticker -> background='transparent', output_format='png'), and an explicit 'Don't use when' exclusion that names the alternative tool (openai_edit_image). This is exactly the when/when-not/alternatives guidance the rubric asks for.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description goes beyond by disclosing the exact response shape, store=true prerequisite for chaining, error handling for model-not-found and rate-limit cases, and the reasoning-effort option. It also warns that temperature and top_p are mutually exclusive in the schema description, which is beyond structured data.

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?

Well-structured with clear sections (Description, Args, Returns, Examples, Error Handling), front-loaded with the key role. Slightly long but every section adds value; no filler. The Args section repeats schema info which is a minor redundancy given 100% schema coverage.

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?

Given 11 parameters, an output schema, and read/write annotations, the description fully covers usage: when to use, what result looks like, error handling, and the chaining prerequisite. Nothing an agent needs to invoke it correctly is missing.

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 schema covers all 11 parameters at 100%, so the description's param list mostly restates what the schema already documents. However it adds clarification that json_object forces valid JSON and notes the output format nuances (markdown vs json payload) that go beyond schema lines. With high schema coverage, the description's param details add marginal value; I credit the clear examples and error-handling mapping that clarify semantics.

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?

We still have an explanation that after scoring format, but the argument is em empty. Describing the purpose of the empty "openai_generate_text" and "openai_generate_text" is an empty description that explains the purpose of generate_text. "Generate text with an OpenAI model through the Responses API" is a clear verb+resource description that distinguishes it from the sibling openai_chat_completion by naming its interface (Responses API) and scope (single-turn and chained generation). The description also explicitly states its role as the default text tool, which differentiates it from siblings.

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?

Explicitly says 'Use this as the default text tool' and gives four usage examples with conditions (including don't-use: use openai_chat_completion for verbatim message history). This is strong usage guidance that prevents both misuse and false negatives.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses that access differs per project, that the response includes the server's default model IDs per capability, and it explains how to interpret two error scenarios ('Authentication failed' and empty filtered results). This adds meaningful behavioral context.

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?

The description is well structured into purpose, arguments, return shape, examples, and error handling. It is detailed but every section serves a purpose and the most important usage guidance appears first.

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?

With an output schema present and four parameters fully documented in the schema, the description adds everything an agent still needs: when to call it, concrete example queries, pagination semantics, and error interpretation. Nothing critical is missing.

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?

Schema description coverage is 100%, so the schema already fully documents all four parameters. The description restates the same parameter semantics and adds only a small filter example ('embedding'), which is useful but not a substantial addition beyond the schema.

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 a specific verb and resource: 'List the model IDs the configured API key has access to, optionally filtered by substring.' This clearly separates it from the sibling generation tools and names the exact purpose.

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?

It explicitly says 'Call this before guessing a model ID' and gives concrete 'Use when' and 'Don't use when' examples, including the actual failure case 'model not found'. It also tells the agent not to use it when only server defaults are needed, since those are applied automatically.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: error handling for invalid model IDs, the returned JSON shape, and the meaning of the 'flagged' field. This goes beyond what annotations alone provide, though it doesn't discuss rate limits, latency, or auth requirements.

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?

The description is well organized with clear sections: purpose, usage guidance, arguments, return format, examples, and error handling. The most important information is front-loaded, and each section serves a distinct purpose without unnecessary fluff.

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?

The description is fully self-contained for effective use. It covers the tool's purpose, when to use it, when not to use it, parameter defaults, return format, example use cases, and a common error scenario. With output schema, annotations, and full schema coverage, nothing critical is missing.

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?

Schema description coverage is 100%, so the schema already documents all parameters. The description mostly restates the same information, such as defaults for model and response_format. It adds minor practical context through examples but does not fundamentally expand parameter understanding beyond the schema.

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 clearly states a specific verb and resource: 'Check text against OpenAI's moderation policy and report which categories it triggers.' It also distinguishes itself from siblings by explicitly saying not to use it for stylistic or factual review, which prevents confusion with openai_generate_text.

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?

Provides explicit when-to-use guidance: before publishing or forwarding user-supplied text, and to explain why a generation was refused. It also gives concrete examples and names the alternative tool to use when moderation is not the need, making the decision boundary very clear.

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

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

The description discloses important non-obvious behavior beyond the annotations: the audio is never returned inline, the tool writes to disk and reports an absolute path, output_path restrictions produce a specific permission error, and invalid voice names cause a recognizable OpenAI rejection message. This adds meaningful context beyond readOnlyHint, destructiveHint, and openWorldHint.

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?

The description is longer than average but well organized with clear sections for behavior, arguments, returns, examples, and error handling. The most critical non-obvious fact—audio is never returned inline—is front-loaded. Minor redundancy with the schema keeps it from a perfect score.

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?

With 8 parameters, an output schema, and meaningful annotations, the description still covers everything an agent needs: all parameters and defaults, the return contract, example invocations, and common error conditions. Nothing critical is missing for correct selection and invocation.

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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds value with the 10,000-character limit, output_path default behavior ('timestamped file in OPENAI_MCP_OUTPUT_DIR'), example instructions ('speak slowly and warmly'), and the returned JSON field meanings. Some redundancy exists with the schema, but the extra usage context is helpful.

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 a specific verb and resource: 'Turn text into spoken audio and write the result to disk.' It clearly differentiates from the transcription sibling by stating the direction of conversion, and the tool name/title align with the described behavior.

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?

The description gives explicit use-when examples such as 'Read this paragraph aloud as an mp3' and an explicit don't-use-when case: 'you want a transcript of existing audio (use openai_transcribe_audio).' This routes the agent to the correct sibling with little ambiguity.

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

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

The description discloses behaviors not visible in annotations: the file is read from disk only from OPENAI_MCP_ALLOWED_DIRS, it is uploaded to OpenAI, the 25 MB API limit applies, and specific error messages map to likely causes. These are practical behavioral details that annotations alone do not provide.

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?

The description is well-structured and front-loaded: a one-sentence purpose, then constraints, Args, return shape, usage examples, and error handling. Despite covering many aspects, each section earns its place and nothing feels redundant or tangential.

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?

Given five parameters, file-size limits, allowed-directory constraints, output format, and error handling, the description covers all necessary context for correct invocation. It also includes the return schema and practical examples, so an agent has everything needed to select and call the tool correctly.

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?

Schema description coverage is 100%, so the schema already documents all five parameters. The description largely restates this information in the Args section, with the only notable addition being the 'vocabulary hint' interpretation of prompt. Since the schema carries the semantic load, a baseline score of 3 is appropriate.

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 a specific verb and resource: 'Transcribe a local audio file to text.' It differentiates itself from siblings like openai_text_to_speech and openai_generate_text by clearly indicating this tool consumes audio and produces text, while specifying supported audio formats.

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?

The description gives explicit use-when examples: 'What was said in this voice memo?' → file_path, and a German interview → language='de'. It also provides an explicit exclusion: 'Don't use when: the file is a video you only want summarised — extract the audio track first.' This is model behavior for routing agents to the correct tool.

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