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

Annotations (readOnlyHint=false, destructiveHint=false) indicate mutability but non-destructiveness. The description adds nuance: 'source Excel is NOT modified' and 'fully reversible before approving the full run', clarifying the session-level mutability. This extra context is valuable and consistent 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 extremely concise (4 sentences) with front-loaded action statement. Each sentence adds essential context: purpose, in-memory behavior, reversibility, and cost update. No superfluous words.

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 the tool's complexity (4 parameters, output schema exists), the description fully covers behavioral context: non-modification, session storage, reversibility, and cost impact. The agent can understand the tool's role and side effects without needing additional explanation.

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?

Input schema covers all 4 parameters with descriptions (100% coverage). The description does not elaborate on parameters beyond the schema, but baseline is 3 due to schema coverage. No additional semantic value is provided by the description.

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 specifies the action ('Add a new entity as a pending row') and the context ('to be included in the full validation run'). This distinguishes it from siblings like 'add_validated_rows' (adds pre-validated rows) and 'include_row' (re-includes excluded rows), providing a unique 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?

The description explains the tool's behavior (no modification to source Excel, stored in session state, reversible before approval) which gives clear context for when to use it. It implicitly advises against using it for permanent modifications, though it lacks explicit 'do not use when' guidance or direct sibling comparison.

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 goes beyond annotations by detailing deduplication, cost quoting, and the append-and-validate behavior. It explains the effect on source Excel and the merging of results. This provides comprehensive behavioral transparency without contradicting annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true agree).

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 concise: one sentence for purpose, two sentences for key behavior, one sentence for precondition. It is front-loaded with the main action and every sentence adds value without redundancy.

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 the tool's complexity (3 parameters, output schema exists), the description covers purpose, behavior, precondition, deduplication, cost quote, and validation merging. It is complete for an agent to understand 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 coverage is 100%, so baseline is 3. However, the description adds significant context about the confirmed parameter's dual behavior, deduplication logic, and cost quoting. It enriches understanding beyond the parameter descriptions, earning a 4.

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 the tool's action: 'Add new rows to a completed validation table.' It specifies the resource (validation table) and the verb (add), and distinguishes from siblings by noting it operates on completed validation tables, unlike add_pending_row or other row-related tools.

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 a clear precondition: 'Only available after full validation completes (status=completed).' It also explains the two-phase use via the confirmed parameter. While it doesn't explicitly list alternatives, the context is sufficient for an agent to decide when to use this tool.

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 indicate mutation (readOnlyHint=false) and non-idempotent (idempotentHint=false). The description adds behavioral context: it starts full validation processing and requires exact cost confirmation to prevent accidental billing. No contradictions 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 concise, using short sentences and a clear workflow structure (numbered steps). Every sentence adds value without unnecessary detail.

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 the presence of an output schema (not shown) and good annotations, the description covers the tool's purpose, parameters, and workflow. It could briefly mention what happens after approval (e.g., the job transitions to a new state), but is otherwise complete for an agent.

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% with good descriptions. The description adds extra value by clarifying that 'job_id' is the same as 'session_id' and emphasizing that 'approved_cost_usd' must exactly match the estimated cost. This goes beyond the schema's basic 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 clearly states 'Approve a preview and start full validation processing,' specifying a specific verb and resource. It distinguishes from sibling tools like 'trigger_preview' and 'wait_for_job' through the workflow mention.

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 explicit workflow steps: call 'wait_for_job' first to reach preview_complete, then call 'approve_validation' with the exact cost. It explains the reason for requiring 'approved_cost_usd' to match the estimate, but does not explicitly mention when not to use the tool or alternatives.

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 provides extensive behavioral details beyond annotations: it explains the pipeline (planner -> search -> QC -> pending_rows), the source label, the cost estimate mode, and that discovered rows land in pending_rows. This exceeds the not read-only, not destructive, open-world hints provided by 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, front-loading the core action. It is slightly verbose with pipeline details but remains efficient and readable. Each sentence adds relevant information.

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 the complexity of the tool (AI-powered discovery pipeline), the description is comprehensive. It covers prerequisites (validated table), workflow steps, output (pending_rows), and next steps (add_validated_rows). The presence of an output schema (though not shown) reduces the need for return value details.

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?

All four parameters are described in the input schema with 100% coverage. The description adds context by explaining the role of session_id (from a completed validation), instruction (natural language request), count (target number), and confirmed (triggers vs quotes). This adds value but is not essential given schema 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 clearly states the tool's purpose: 'Discover and add new rows to an existing validated table using AI-powered search.' It specifies the resource (rows), action (discover/add), and method (AI-powered search). This distinguishes it from siblings like add_validated_rows (which validates pending rows) and get_results (which retrieves data).

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 explains when to use the tool (to discover new rows via AI) and outlines the two modes (confirmed=False for cost estimate, confirmed=True to enqueue). It mentions the dependency on a completed validation session and points to add_validated_rows for subsequent validation. However, it does not explicitly state when not to use it or list all alternatives.

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 indicate readOnlyHint=false (mutation) and destructiveHint=false. The description adds crucial behavioral details: the two-step confirmation process and reversibility, which are not in annotations. No contradiction.

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?

Three succinct sentences, front-loaded with the main purpose. Every sentence adds essential information without redundancy.

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 100% schema coverage and presence of an output schema (not shown, but context signals indicate it exists), the description is complete, covering usage pattern, reversibility, and relationship to sibling tools.

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 covers all parameters with descriptions (100% coverage). The description adds contextual usage for the 'confirmed' parameter, explaining its role in the two-step flow. This adds value beyond the schema's basic description.

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 the action (exclude) and the target (a row from the full validation run), distinguishing it from siblings like 'include_row'.

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 guides the agent to call with confirmed=False first to preview a warning, then re-call with confirmed=True. Also notes reversibility via include_row, providing clear when-to-use and alternative.

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 indicate readOnlyHint=true, so the description adds the unit 'in USD' and 'current' but no further behavioral traits. With annotations present, the description provides adequate context beyond what is structured.

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?

A single, front-loaded sentence efficiently states the tool's purpose without redundancy.

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 zero parameters and presence of an output schema, the description suffices. It conveys the essential information (balance retrieval in USD) for a read-only tool.

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?

No parameters exist, so the baseline is 4. The description clarifies the return value (balance in USD), which adds meaning beyond the empty input schema and complements the output 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 uses a specific verb ('Return') and resource ('account credit balance'), clearly indicating what value is retrieved. It stands out among sibling tools like get_usage which likely returns different information.

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 implies usage for checking balance but does not provide explicit when-to-use or when-not-to-use guidance. For a zero-parameter tool, this is minimally acceptable.

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, indicating a safe read operation. The description adds behavioral context by explaining that the tool returns intermediate statuses and suggests polling intervals. However, it does not disclose auth requirements or rate limits, which would further enhance transparency.

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 very concise: one opening sentence plus a bullet list of three statuses. Every sentence adds value, and the structure front-loads the key action. There is no redundancy or 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?

Given that an output schema exists (as per context signals), the description does not need to detail return values. It covers the main use case, statuses, and follow-up actions. It could mention polling timeout or when to stop, but it is sufficiently complete for a polling tool with sibling 'wait_for_conversation' for automatic polling.

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 input schema already documents both parameters. The description adds no additional parameter details beyond what is in the schema (e.g., 'Conversation ID returned by...'). Per the rubric, baseline is 3 when coverage is high, and the description does not add meaningful extra 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?

The description clearly states the tool's purpose: 'Poll a conversation for new messages or a status change.' It specifies the verb 'poll' and the resource 'conversation', making the action unambiguous. The list of key statuses further distinguishes this tool from siblings like 'send_conversation_reply' and 'get_job_status'.

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 explicit guidance on when to use the tool (polling for new messages or status change) and includes specific statuses with recommended actions: 'poll again in ~15s', 'send_conversation_reply', and 'switch to get_job_status'. This gives clear context for alternative tools, exceeding basic usage guidance.

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. Description adds minimal behavioral context (live, running job) but no extra safety or side-effect details beyond 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?

Two sentences with a clear front-loaded purpose and no wasted words.

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, the description adequately covers purpose and key parameter usage, though it could optionally clarify behavior when since_seq is omitted.

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?

Input schema has 100% coverage, so baseline 3. Description reiterates the since_seq behavior but does not add new meaning 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 the verb 'Fetch' and the resource 'live progress messages for a running job', distinguishing it from siblings like get_job_status which focus on overall status.

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 a clear usage hint for the since_seq parameter to fetch only new messages, but does not explicitly mention when not to use or compare to alternatives.

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?

Description confirms it is a one-shot, non-blocking read operation, consistent with readOnlyHint. It adds value by mapping statuses to recommended next actions, giving the agent a behavioral model.

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?

Concise and well-structured: opening sentence, usage guidance, bullet list of status mappings. Every sentence is informative with 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?

With one fully-described parameter, good annotations, and output schema, the description covers purpose, usage, and next steps. No gaps for a simple query tool.

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 single parameter job_id is fully described in the schema (100% coverage). The description adds context by listing where job_id comes from (upload_file, start_table_validation, start_table_maker), which aids in value selection.

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?

Description starts with 'One-shot job status check,' clearly stating the purpose. It contrasts with wait_for_job, making it easy to distinguish.

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 'Prefer wait_for_job for tracking long-running jobs' and provides status-specific guidance (queued/processing → wait_for_job, preview_complete → approve_validation, etc.).

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 indicate readOnlyHint=true. Description adds value by listing what is returned (preview table, excluded rows, pending rows, ignored columns, row order) and the purpose (review). No contradiction.

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?

Three sentences, each serving a purpose: state action, list return items, state usage context. No extraneous information. Front-loaded with the verb and resource.

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?

Despite having an output schema, the description still explains the key components returned. For a simple read-only tool with one parameter, this is complete and sufficient guidance.

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 has 100% coverage with a single parameter 'session_id' described only as 'Session ID.' Description does not add additional semantics about the parameter beyond what the schema provides, so 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?

Clearly states 'Get the current structural editing state of a session,' specifying the action (get), resource (preview state), and scope (session). Distinguishes from sibling tools like 'trigger_preview' and 'add_pending_row' which modify state.

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 to use it 'before triggering the full validation run' to review current state. Does not mention alternatives or when not to use, but the context is clear enough for an AI agent.

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?

Adds value beyond annotations by revealing that table_metadata.json is automatically embedded, avoiding separate HTTP fetches. Also outlines key response fields. Annotations already indicate readOnlyHint=true, so the description complements without contradiction.

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 a clear opening sentence, bullet points for key response fields, and a 'START HERE' emphasis. Every sentence is informative and earns its place; no 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?

For a tool with one parameter, high schema coverage, and an output schema, the description is comprehensive: explains purpose, parameter usage, and response structure. Provides a mental map of the output without redundancy.

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%, baseline is 3. Description adds clarifying detail that job_id and session_id are the same string, and implies job_id must be for a completed job, which goes beyond the schema's description.

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?

Description clearly states 'Fetch the final validated/enriched results for a completed job,' providing a specific verb, resource, and constraint. It distinguishes from sibling tools like get_job_status or get_preview_state by focusing on completed job results.

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 context that job_id equals session_id and emphasizes starting with results.markdown_table. However, it does not explicitly state when to use this tool versus alternatives (e.g., get_job_status, get_preview_state), lacking exclusions or when-not scenarios.

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, making the behavioral expectations clear. The description adds a date format hint but does not discuss other behaviors like pagination or rate limits, which are not covered by 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?

Two sentences communicate purpose and a key format detail with no wasted words.

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 the presence of an output schema and annotations, the description covers the essential purpose and date format. It could detail what constitutes 'usage history' but remains adequate for a read-only list tool.

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 description does not need to compensate. The date format hint redundantly reinforces parameter descriptions, adding no new meaning.

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 'Return API usage history', which specifies a verb and a resource. The purpose is distinct from sibling tools like get_balance or get_conversation.

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 no guidance on when to use this tool versus alternatives. It lacks any context about suitable scenarios or prerequisites.

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?

Adds behavioral context beyond annotations: no confirmation required and valid only before approval. This informs the agent about side effects and constraints without contradicting 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?

Two sentences, no extraneous words, front-loaded with the core action. Every sentence provides essential information.

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 a simple tool (2 params), the description covers action, constraints, and timing. Could mention error conditions, but overall adequately complete.

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 descriptions cover both parameters (session_id and row_key) completely. The description does not add additional semantic value beyond what the schema provides, so baseline score of 3 applies.

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 uses the specific verb 're-include' and resource 'row', clearly stating the action. It naturally distinguishes from sibling 'exclude_row' by implying the opposite operation.

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 states no confirmation needed and the timing constraint ('at any point before approving the full validation run'). While it doesn't list alternatives, the context is sufficient for typical use.

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 fully discloses behavioral traits: the cost estimate formula, caching behavior, merging of results, and lack of QC on patch runs. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with the described non-destructive modification, and no contradictions exist.

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 concise with a front-loaded purpose statement and subsequent paragraphs explaining behavior in a logical flow. Every sentence adds necessary information without redundancy.

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 the complexity (4 parameters, nested objects, output schema), the description covers all essential aspects: precondition (completed validation), two-phase execution, caching, cost estimation, and result integration. It is complete for an agent to determine correct usage.

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. The description adds value by explaining the 'confirmed' parameter's role in toggling between estimate and execution, and provides context for the cost calculation. For other parameters, the schema descriptions already suffice.

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 starts with 'Add a new column to a completed validation table,' which is a specific verb and resource. It clearly distinguishes this tool from siblings like start_table_validation or refine_config by focusing on adding a column after validation completion.

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 explains the two-mode behavior (confirmed=False for cost estimate, confirmed=True for execution) and explicitly states it is only available after full validation completes. However, it does not explicitly mention when not to use it or alternative tools for modifying existing columns.

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 indicate non-readonly, non-destructive, open-world. Description adds auto-preview behavior and the effect of defer_preview. Does not detail persistence or rollback, but adds useful 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?

Two terse paragraphs: purpose with examples, then defer_preview guidance. No excess words. Highly efficient.

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?

Assumes existence of conversation/session (required params) but does not explain lifecycle context (e.g., must have started refinement via start_table_validation). Output schema exists so return values not needed, but prerequisites are implicit.

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% with clear descriptions. Description adds example instructions and clarifies defer_preview usage beyond schema (e.g., 'prevents premature auto-preview'). Baseline 3 improved to 4.

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?

Description clearly states the verb 'refine' and resource 'validation config', with natural language instructions. Examples provided distinguish from sibling tools like 'start_table_validation' or 'approve_validation'.

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 specific guidance on when to set defer_preview to avoid premature auto-preview. However, does not explicitly compare to sibling tools for granular edits (e.g., exclude_row, add_pending_row) that might be alternatives.

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 annotations, the description adds critical behavioral context: it is a display preference, does not affect validation, and rows not in the list are sorted to the end. No contradictions.

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?

Three concise sentences, front-loaded with purpose, then clarifying details. No wasted words.

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 simple reordering tool with good annotations and schema, the description covers all key behavioral aspects and is complete.

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% and both parameters are described. The description adds value by explaining the sorting behavior for omitted rows, going 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 the tool sets the output row order for the validation run and explicitly clarifies it is a display preference, distinguishing it from tools that affect validation or row inclusion.

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 explicitly states when to use (to reorder display) and what it does not do (affect validation), with clear implications that alternatives like include_row/exclude_row are for validation changes.

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?

Discloses that the tool triggers a stateful action (openWorldHint=true) and requires polling for AI response, adding value beyond annotations. However, does not detail rate limits, authentication needs, or potential delays.

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?

Two concise sentences: one for purpose, one for next step. No redundant or vague phrasing; efficient and clear.

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?

Tool is straightforward and the description, combined with annotations and output schema (not shown but present), covers key behavioral aspects. Explains the polling pattern, which is critical for correct usage.

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?

Input schema covers 100% of parameter descriptions, so the description adds no additional parameter semantics. 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?

Description clearly states the action (send a user reply) and context (ongoing conversation, interview or table-maker). Distinguishes from sibling tools like get_conversation and wait_for_conversation, which serve different purposes.

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 instruction to poll get_conversation after sending, guiding the agent on the expected workflow. Lacks explicit when-not-to-use or alternatives, but for a focused tool this is sufficient.

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 indicate readOnlyHint=false and openWorldHint=true. The description goes well beyond by detailing the three-phase workflow, auto-approve option, cost implications, and expected outputs (XLSX, viewer URL, metadata). It explains the approval gate and how wait_for_job interacts with phases, providing rich 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 with clear sections for inline text, file upload, and phases. It is informative but slightly lengthy; some details like the exact return of upload_file could be omitted. Overall, it is organized and front-loaded with key purpose.

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 the tool's multi-phase complexity, the description covers all essential aspects: input formats, phase details, approval gate, auto-approve, output types, and links to other tools (upload_file, wait_for_job, approve_validation). The output schema exists to cover return values, so completeness is excellent.

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% with clear descriptions for all three parameters. The description adds value by explaining the mutual exclusivity of text and s3_key, and clarifying the behavior of auto_approve. However, most parameter meaning is already in the schema, so the description enhances rather than replaces.

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 the tool submits a reference-check job to fact-check text or documents. It distinguishes itself from sibling tool start_table_validation by explicitly stating not to use that for PDFs, and provides two input modes: inline text or S3 key of an uploaded file.

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 explicit when-to-use guidance: for fact-checking text with 4+ claims, and when not to use: fewer claims may produce low-quality results. It also warns against using start_table_validation for PDFs, naming an alternative tool.

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 indicate the tool is not read-only and not destructive, but the description adds transparency by detailing the conversation initiation and the auto_start behavior, which skips confirmation steps. It does not contradict 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 concise, front-loaded with the purpose, includes a clear example, and explains parameters efficiently. Every sentence serves a purpose without redundancy.

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 the tool's complexity, the description covers the main parameters and usage. With an output schema present (as per context signals), the description does not need to explain return values. It is complete for effective tool 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%, but the description adds value by providing examples for the message parameter and clarifying when to use auto_start. This goes beyond the schema descriptions, which are already adequate.

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 the tool starts a Table Maker conversation for generating research tables, using a specific verb and resource. It provides an example and distinguishes itself from sibling tools like start_reference_check or start_table_validation by its unique 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?

The description explains how to use the tool, including the auto_start parameter behavior, but does not explicitly mention when to use it versus alternatives or when not to use it. It lacks guidance on prerequisites or exclusion criteria.

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 indicate the tool is not read-only and not destructive. The description adds behavioral context: config generation and preview are free, full validation is charged at approve_validation, and balance insufficiency leads to an error. It does not fully describe all side effects, but adds value beyond 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 separation of concepts and front-loaded key information. It is slightly verbose but every sentence adds value. Could be more concise, but efficiently conveys important details.

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 the tool's complexity (5 parameters, output schema exists), the description covers the workflow, charging model, and error handling. It does not detail return values, but output schema likely provides that. It is adequately complete.

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 input schema already provides 100% coverage with descriptions, but the description elaborates on parameters like instructions and config_id, explaining their effects (bypassing interview, skipping matching). This adds meaningful context 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 the tool's purpose: to confirm upload and detect matching prior configs. It specifies the action verb ('confirm', 'detect'), the resource (upload and prior configs), and distinguishes from siblings like start_reference_check or start_table_maker.

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 explicitly instructs to call this immediately after upload_file completes, and explains when to use config_id vs instructions. It also mentions that if match_score >= 0.85, a prior config can be reused directly, providing clear usage context.

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 provide basic traits (non-readonly, non-destructive). The description adds specific behavioral details: 'clears skip_auto_preview and queues the preview.' This goes beyond annotations and gives the agent a better understanding of side effects.

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 three sentences, each serving a distinct purpose: stating the action, clarifying context, and explaining behavior plus next step. No filler or redundancy.

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 the tool's low complexity (single param, output schema exists), the description covers purpose, usage context, behavioral effect, and next step. It lacks mention of return values but is otherwise complete.

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%, with the session_id parameter already described as 'Session ID to trigger preview for.' The description does not significantly elaborate beyond that, but it reinforces usage context by mentioning session_id in the follow-up step. Baseline 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 clearly states the verb 'Trigger a preview run' and specifies the resource ('preview run') and context ('after structural editing is complete'). It distinguishes itself from sibling tools by mentioning it is called after row/column edits, providing explicit examples.

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 explicitly instructs when to call this tool ('after finishing row/column edits') and provides follow-up steps ('call wait_for_job(session_id) to track progress'). While it does not mention alternatives or when not to use, the guidance is clear and actionable.

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?

Description says 'update in place' implying modification, consistent with readOnlyHint=false. However, no additional behavioral details beyond annotations; no mention of overwrite behavior or side effects.

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?

Two terse sentences, no fluff, critical info front-loaded. Every word contributes.

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?

Output schema exists, so return values are covered. However, the description omits what 'update in place' means for previous results (overwrite vs new version). Functional but leaves some questions for a validation tool.

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% with adequate parameter descriptions. Description adds context for source_version ('pin...latest'), but largely redundant with schema. Baseline 3 applies.

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?

Description clearly states 'Re-run validation on a previously processed table', specifying verb and resource. No ambiguity; distinguishes from siblings like add_validated_rows.

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 guidance on the source_version parameter but lacks explicit when-to-use vs alternatives. Implied for re-running validation, but could contrast with add_validated_rows or start_table_validation.

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?

Discloses the two-step behavior, presigned URL expiration (15 minutes), and transport dependency. Annotations (readOnlyHint=false) are consistent; description adds valuable context beyond 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?

Well-structured with headings and examples, but slightly verbose. Front-loads purpose and uses clear sections, though some repetition could be trimmed.

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 tool complexity (two modes, transport-dependent) and presence of output schema, the description covers fallback logic, expiration, and prerequisites thoroughly.

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%, but description adds extra context for file_path (recommendation, transport dependency) and example usage. Adds meaning beyond 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?

Clearly states 'Upload a file to Subindex' and distinguishes two modes based on transport. The verb+resource is specific and distinct from sibling tools.

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 guidance: 'always try with file_path first', explains when to use without file_path, and notes shell access requirement. Offers alternatives for different transports.

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 the synthetic progress behavior, timing curve, and detailed return conditions. Annotations already indicate readOnlyHint=true, and the description adds significant behavioral context beyond that.

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 thorough and well-structured with bullet points for return conditions and parameter guidance. Although lengthy, every sentence adds value and the organization aids readability.

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 the output schema exists, the description covers all necessary aspects: purpose, usage, parameter guidance, return conditions, and scope. No gaps remain for effective tool 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?

While the input schema covers 100% of parameter descriptions, the description adds contextual guidance (e.g., expected_seconds ranges for different turn types) that enhances 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 the tool waits for a conversation turn to complete and emits synthetic progress. It specifies return conditions and distinguishes itself from manually polling get_conversation.

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 explicitly recommends this over polling get_conversation, provides context for all conversation types, and gives detailed guidance on expected_seconds values based on turn type.

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 extensive behavioral details: the polling cycle (fetch messages then status), progress monotonicity, progress geometry (lazy split with 80/20 rule), terminal vs intermediate states, and the warmup mechanism. These go far beyond the annotations (readOnlyHint, openWorldHint) and are consistent with them.

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 fairly long but well-organized with section headings (Architecture, Progress geometry, etc.). The key purpose and preference statement are front-loaded. Every section provides necessary detail for correct usage, so it earns its length.

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 the complexity (4 parameters, output schema present), the description is complete: it explains return shape (same as get_job_status), covers all parameters with usage notes, details internal polling architecture, and provides edge-case handling (warmup, intermediate phases). No gaps remain.

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?

All 4 parameters have schema descriptions (100% coverage). The description adds extra context: job_id is same as session_id, timeout_seconds default with real-world time guidance, warmup_seconds with use-case-specific advice. This adds meaning beyond the schema, justifying a score above baseline 3.

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 states 'Wait for a job to reach a terminal state, emitting live MCP progress notifications.' This is a specific verb+resource combination and explicitly distinguishes from sibling tool get_job_status by stating it is 'preferred over manually looping get_job_status.'

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 clear usage guidance: it is preferred over get_job_status for waiting, and it explains when to use warmup_seconds (e.g., 300 for instructions= mode). However, it does not explicitly state when not to use this tool or list alternatives beyond get_job_status.

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