submit_clarification_request

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, and the description adds real behavioral context on top: this role never writes files, Meeting Mode resumes automatically, and the caller must immediately act on a non-null action_required rather than ending its turn. That is exactly the kind of follow-up-loop disclosure annotations cannot carry. The one weak spot is a mild tension between "Read-only role" and readOnlyHint=false, which could momentarily confuse an agent about whether the call mutates state.

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 purpose statement is front-loaded and each subsequent sentence carries an operational rule (auto-continuation, action_required, meeting_mode_notice prefix). Some wording is dense, notably the nested parenthetical about expected_report_fields and the stray line breaks, but nothing is truly redundant.

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 submission tool inside an automated workflow this is close to complete: it states the precondition, the non-mutation of files, and how to handle the two key response fields, and an output schema exists so return values need not be restated. The gaps are the absence of guidance on wait_seconds/settling behaviour in prose and no mention of failure or invalid-handoff handling.

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 75% and the ClarificationRequest sub-object carries its own description, plus project_id, execution_id and wait_seconds are all documented in the schema, so the structured data does most of the work. The description's contribution is naming the expected report fields, which does not add much beyond the nested schema definition and adds nothing about wait_seconds or the blocking behaviour of the call. Baseline 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?

"Finish an active ChatGPT Meeting Mode SD/RD check" gives a specific verb plus a named workflow stage, and the parenthetical (expected_report_fields are blocking_question, no_blocking_question, rationale) pins down exactly which payload this tool submits. It implicitly separates itself from submit_agent_report / submit_clarification_response by tying the call to a Meeting Mode SD/RD handoff, though it never names those siblings explicitly.

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?

Usage is implied through the precondition (there must be an active check whose expected_report_fields match), and the description gives firm post-call directives for action_required and meeting_mode_notice. However, it gives no explicit when-not guidance and does not distinguish this from resolve_clarification, submit_clarification_response, or submit_agent_report, so an agent must infer which submission tool is correct from context alone.

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