Converra

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description goes beyond them with substantive behavioral detail: feedback attaches to the agent not the run, conditions all FUTURE generations, triggers immediate forced regeneration by default, and other runs pick up corrections later. This is exactly the extra context the bar rewards.

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 tightly-packed sentences, front-loaded with the core action. Dense but every sentence carries distinct behavioral information; no filler. Slightly heavy but earns its length 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?

Given 9 params, nested objects, 100% schema coverage, and a destructive=false? no—destructive write with side effects, the description covers the temporal/persistence semantics (future generations, immediate regeneration) that the schema cannot express. Nothing essential is missing for correct 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 description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the agent-scoping semantics that motivate agentId's default behavior and the regeneration trigger that frames triggerRegeneration. Adds value on top of already-rich schema docs.

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?

States a specific verb+resource: 'Record disagreement with a run insight.' Clear what the tool does and distinguishes from read tools like get_run_insights, though it doesn't explicitly contrast with regenerate_run_insights or batch_regenerate_insights which are adjacent operations.

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?

Explains the situation well: when the user disagrees with an insight and wants a correction that conditions future generations. No explicit when-not-to-use guidance or named alternatives (e.g. vs regenerate_run_insights), but context is 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely useful behavioral context beyond that: feedback is stored per-agent and propagated as context to future optimizations, which tells the agent the write has lasting downstream effects. It stops short of noting permission requirements or whether feedback is editable/deletable.

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, front-loaded with the core action before the enum taxonomy. The feedbackType examples are the only slightly redundant portion versus the schema, but they aid selection and are worth the space.

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?

No output schema exists, and the description adequately covers the effect of the call (per-agent storage, propagation to future optimizations). It omits return shape and whether optimizationId/variantId are needed for certain feedback types, which would help an agent compose a fully valid call.

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 7 parameters including the enum semantics for feedbackType and rating. The description's explanation of reaction/constraint/direction largely restates what the schema's feedbackType description provides, so it adds examples but little net new 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?

States a specific verb and resource ('Add feedback ... on an optimization result') and immediately scopes what feedback comprises (rating, comment, or both). This distinguishes it from the nearest sibling add_insight_feedback, which targets insights rather than optimization 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?

Gives explicit when-to-use guidance for each of the three feedbackType values with concrete examples ('never remove the disclaimer', 'focus on reducing hallucination'). It does not, however, state when NOT to use this tool or how it differs in practice from add_insight_feedback, so routing between the two feedback tools 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?

Annotations declare the tool is not read-only, not destructive, and closed-world, so the safety profile is largely covered. The description adds genuinely useful context the annotations do not: "Scenarios are appended - existing ones are preserved," which reassures the agent that a mutation will not overwrite the existing golden suite. It does not mention any limit on scenario count, validation rules, or return shape.

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 tight sentences: purpose first, then usage, then the append/preserve guarantee, with no filler or repetition. Every sentence adds a distinct piece of 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?

For a two-required-param mutation tool with a rich nested schema and no output schema, the description covers what it does, when to use it, and the append semantics. It leaves out return behavior and any limits on scenario count or validation, which are minor but real gaps.

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%, including nested scenario fields and the superadmin-only customerId, so the schema already carries the parameter burden. The description only implicitly references agentId via "an agent's existing golden suite" and adds no format or constraint detail beyond the schema; 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?

States a specific verb (add) plus resource (custom regression test scenarios) and target (an agent's existing golden suite), which separates it from siblings like get_regression_suite and regression_test without needing to name them. An agent can identify the operation from the first clause alone.

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?

"Use this to strengthen the regression suite with scenarios targeting specific behaviors (e.g., human escalation, multi-language, support routing)" gives a clear context and concrete examples of intended use. It stops short of naming when NOT to use it or pointing to an alternative (e.g., dataset or production-test tools), so no explicit exclusions.

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, destructiveHint=false, and openWorldHint=false, so safety is covered; the description's 'without running simulations' usefully adds that no execution/side effects occur. It does not mention that customerId requires superadmin privileges or what the analysis output contains, so it adds only modest context 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?

A single front-loaded sentence with a clear verb, object, and disambiguating clause; no filler or repetition of the title.

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 three-parameter, read-only analysis tool with full schema coverage and no output schema, the description conveys what is analyzed and what kinds of results come back (weaknesses, recommendations). It could say more about how the optional promptId/customerId change the result, but nothing essential to calling it 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%, and each parameter (prompt, promptId, customerId) is already documented in the schema, including the superadmin note. The description adds no parameter-level meaning beyond what the schema states, so the 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?

The description names a specific verb ('Analyze'), a specific resource ('an agent's system prompt structure'), and the concrete outputs ('weaknesses', 'improvement recommendations'). The trailing 'without running simulations' also distinguishes it from the sibling simulate_agent at a glance.

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?

'Without running simulations' tells the agent this is a static, non-executing review, which contrasts it with simulate_agent and run-oriented siblings. It stops short of an explicit 'use this instead of X when Y' statement, but the selection context is 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description usefully adds that the original agent prompt content is replaced, clarifying what is destroyed, but says nothing about reversibility or required permissions despite a rollback_production_test sibling existing.

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 that states the action and its effect with no wasted words. The destructive outcome is placed immediately after the verb.

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 destructive mutation with no output schema, the description covers the effect but omits reversibility, permission requirements, and post-apply state. Annotations carry the safety hint, so it is adequate but leaves real gaps for a state-changing operation.

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 all three parameters are documented in the schema, making the baseline 3. The description only echoes the 'winning variant' defaulting behavior already stated for variantId in the schema and adds no new syntax or ID-format detail.

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 a specific verb (apply/deploy), resource (variant), and effect (replace the original agent prompt content). This lets an agent distinguish it from validate_variant and get_variant_details, though it does not explicitly name those 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?

There is no explicit when-to-use or when-not-to-use guidance, and no reference to alternatives such as validate_variant or decide_approval. The word 'winning' faintly implies this happens after a variant wins, but the usage context 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is known. The description adds little beyond that — 'Returns progress summary' hints at the output shape, but nothing about the overwrite behavior of `force` or the batch limit, which lives entirely in the schema.

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 short sentences, zero filler, with the core action front-loaded and the usage trigger immediately after. Every sentence carries 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?

For a destructive batch mutation with no output schema, the description is thin: it does not mention the default limit of 50 (which bounds scope), the overwrite behavior, or how it relates to the single-run sibling. The 'progress summary' note partially covers the return, but an agent must open the schema to understand the operation's blast radius.

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 the schema descriptions are rich (overwrite semantics, defaults, max values, superadmin restriction). The description contributes no parameter detail beyond what the schema already provides, so the 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?

States a specific verb (regenerate) plus resource (insights) with a clear scope qualifier ('for all runs of an agent'), which distinguishes it from a single-run variant. However, it never contrasts itself with close siblings like regenerate_run_insights or refresh_agent_insights, so the boundary is inferred rather than stated.

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?

'Use this to bulk-fix broken insights or refresh after changes' gives concrete when-to-use triggers. It stops short of naming alternatives (regenerate_run_insights, refresh_agent_insights) or when-not conditions, so an agent could still pick the wrong sibling for a single run.

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 only say it is not read-only, not destructive and not open-world. The description goes well beyond that by disclosing the async job pattern (immediate jobId), the execution cost profile (baseline once + every challenger), and the statistical method (3 runs per scenario, median scoring), which materially affects how an agent should budget and follow up. It does not state auth/scoping requirements, e.g. the superadmin-only customerId path.

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, front-loaded with what the tool does, then how it runs, then the async handoff. Every sentence carries distinct information and none restates the name or annotations.

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 no output schema, the description correctly covers the immediate return (jobId) and the polling path, and it hints that goal affects winner selection. It does not describe the shape of the per-scenario delta results the agent will eventually retrieve, but the get_benchmark_status pointer largely compensates.

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 every parameter including the baseline/challenger ordering, goal enum, and fineTunedModels pricing fields is already documented. The description reinforces the baseline-vs-challenger concept and the default run count but adds no syntax or format beyond the 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?

States a specific verb and resource ('Compare multiple LLM models on the same scenarios for an agent') plus the mechanism (baseline run once, then each challenger, per-scenario deltas). An agent can distinguish this tuning/benchmark job from siblings like start_model_test or simulate_ab_test without opening the 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?

Provides clear operational context: it returns a jobId immediately and directs the caller to get_benchmark_status for polling, which is exactly the when/what-next guidance an agent needs for an async tool. It stops short of naming when to prefer this over adjacent tools such as optimize_model or simulate_ab_test, so no explicit exclusions or alternatives are given.

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 annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description discloses irreversibility ('Permanent for the project'), idempotency semantics, the refusal mode for a conflicting version, and that the call has no side effects on freezing/training/spend. This is rich behavioral context the annotations alone do not carry.

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?

Four tight sentences, front-loaded with the core action (bind the frozen version), followed by persistence semantics, side-effect disclaimers, and scope. No filler and no repetition of schema content.

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 mutation tool with no output schema, the description covers purpose, permanence, idempotency, refusal behavior, alternatives, and side-effect profile. An agent has everything needed to decide when and how to call it 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 all four parameters are already documented with their source tools (projectId, versionId). The description reinforces that versionId comes from list_dataset_versions but adds no new syntax, format, or constraint detail, and does not address the superadmin-only customerId. 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?

States a specific verb (bind) and the exact resource (the one frozen dataset version a project trains on), and proactively contrasts with freeze_dataset_version by asserting 'Freezes nothing, trains nothing, spends nothing.' An agent can distinguish this from the freeze/list siblings without opening a 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?

Explicitly routes the agent to list_dataset_versions as the source of the version, states the when-not (a different version is refused), and names the alternative path ('open a new project to train on another version'). Repeat-call behavior (same version = no-op) is also spelled out.

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 frames the call as read-only diagnosis ('diagnosis only', 'Does NOT trigger a restart'), but the annotations declare readOnlyHint=false and destructiveHint=true, so the safety profile an agent relies on is contradicted. Although the description usefully enumerates the returned payload and the negative scope, the direct conflict with the structured safety hints forces the floor score.

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 tight sentences, front-loaded with purpose, then output content, then scope restriction. Every sentence carries distinct information 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 no output schema, the description does the work of describing the return (failure classification, suggested next strategy, per-metric breakdown), and parameters are fully covered by the schema. The residual gap is side-effect/permission behavior, which the contradictory annotations leave ambiguous.

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 only two parameters, and the schema already documents both processId and the superadmin-only customerId. The description adds nothing about parameter meaning or format, so the 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?

States a specific verb and resource with the triggering condition: 'Diagnose why an optimization failed to produce a winner.' The closing 'Does NOT trigger a restart — diagnosis only' separates it from mutation siblings such as trigger_optimization, optimize_model, and fix_worst_run without requiring a schema read.

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?

Gives a clear triggering context (an optimization that produced no winner) and one explicit exclusion (it does not restart the optimization). It stops short of naming the alternative tools an agent should reach for when it wants details, run-level diagnosis, or an actual re-run.

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 genuine behavioral context beyond the annotations: a closed project 'records nothing further' (consequence of closure) and a diagnosed rerun spawns a new project referencing rerunOfProjectId. 'Scope: write' is consistent with readOnlyHint=false, though it doesn't clarify why closure isn't flagged destructive.

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 compact sentences, front-loaded with the core action. No padding, though the rerunOfProjectId sentence is arguably tangential to an invocation-time description.

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 no output schema the description covers the mutation's consequence and scope well enough, but it omits permission/error behavior and leaves the required 'reason' enum selection entirely to the schema. Adequate but with clear gaps for a state-changing 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?

At 67% schema coverage the schema already documents projectId and customerId (superadmin-only). The description clarifies the role of 'reason' as the closure justification but adds no enum semantics, and its rerunOfProjectId reference is not an input parameter, which may confuse rather than help.

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?

States a specific verb+resource ('Close a fine-tuning project') and identifies the required trigger input ('with its reason'). This clearly differentiates it from create/get/list_fine_tuning_projects siblings, though it never names an alternative 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?

Provides no when-to-use or when-not guidance. 'Scope: write' hints at the operation class, and the enum reasons imply scenarios, but the description never says at what point in a project's lifecycle an agent should close it versus other actions.

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 only declare it is a non-read-only, non-destructive, closed-world write. The description adds genuinely non-obvious behavioral context: parameter validity is model-dependent (Opus 5 accepts reasoningEffort and rejects temperature/topP), which prevents malformed calls. It does not cover permissions, whether creation is reversible, or rate limits.

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 tight sentences with the critical constraint front-loaded as 'IMPORTANT' and the workflow caveat marked 'NOTE'. No filler. The trailing create_run sentence is slightly tangential to the act of creation, but it earns its place as sequencing guidance.

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 16-parameter write tool with no output schema, the description covers the highest-risk decision (model selection and its parameter consequences) and the immediate next step in the workflow. It does not mention what the call returns (e.g., an agent ID needed for create_run), which is the main remaining gap.

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, but the description adds cross-parameter semantics the schema cannot express: that llmModel gates which sampling/reasoning parameters are legal. That is meaningful beyond the per-field descriptions, though the remaining 15 parameters are left entirely to 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?

States a specific verb+resource ('Create a new agent') and adds the platform context ('for optimization'), which distinguishes it from sibling read/mutation tools like get_agent, list_agents, and update_agent. Sibling differentiation is implied by the verb rather than stated explicitly, so it falls just short of a 5.

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?

Gives concrete when-to-use guidance: llmModel must be specified, the agent should ask the user which model is in use when unspecified, and it names the follow-up step and sibling tool ('upload run transcripts with create_run before running optimization'). No when-not-to-use or prerequisite/permission guidance is offered, keeping it below 5.

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 annotations only declare it as a non-read-only, non-destructive, closed-world write. The description adds genuinely useful behavioral context beyond that: the process is deterministic, candidates are admitted only if they are verified successes on their own checks, and it has no training cost or spend. This is a meaningful disclosure for a mutation tool, though rate limits and permission requirements remain unaddressed.

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 tight sentences with the purpose and mechanism front-loaded and the cost/no-training clarification placed last where it matters. Dense but no wasted phrasing; the breakdown of steps ('extracts... clusters... admits...') is arguably more detail than a selector needs, keeping it just short of 5.

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 four-parameter mutation tool with full schema coverage and no output schema, the description pairs the purpose with the non-training/no-cost guarantee, which is what an agent most needs to avoid misfiring. It stops short of describing the returned handle (e.g., a dataset id) or next steps, but no output schema exists so this is largely acceptable.

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 all four parameters, including the superadmin-only customerId and the splitConditionKeys default/max, are already documented in the schema. The description's mention of 'instruction version × conditions' loosely gestures at the splitting concept but adds no syntax or constraint detail beyond the schema, so 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?

The description states a specific verb (curate/create) and resource (a dataset from an agent's completed runs) and describes the concrete mechanism: extracting candidates, deterministic clustering by finding type × instruction version × conditions, and admitting verified successes. This clearly distinguishes it from read-side siblings like get_dataset and list_datasets.

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 rather than stated: it's the tool that builds a dataset from completed runs, and 'Trains nothing and spends nothing' rules out a training interpretation. However, it never says when to prefer this over siblings like list_dataset_examples, freeze_dataset_version, or bind_dataset_version, nor does it name any prerequisite or exclusion.

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, destructiveHint=false, openWorldHint=false. The description adds real context beyond that: no training occurs, no version is bound, no money is spent, and the later steps require the approve scope. It stops short of describing what the call returns or its own authorization requirements, but it meaningfully expands on the annotation surface.

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 filler. The core action and scope come first, with the clarifying non-effects and hand-off to the approval flow following. Every clause carries 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?

For a non-destructive create with no output schema, the description covers what is created and what is explicitly not triggered. It does not say what the call returns (e.g., a project id to use with get_fine_tuning_project) or the scope needed to create the project itself, a small remaining gap.

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 83%, so the schema already documents parameters including the optional datasetId and the nested objective object. The description restates the cardinality ('one agent, one objective, optionally the dataset') but adds no syntax, format, or enum detail beyond the schema, so the 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?

States a specific verb and resource ('Open one fine-tuning pass') and immediately bounds the scope: one agent, one objective, optional dataset. It is clearly distinguishable from siblings like freeze_dataset_version or decide_approval, which it names as separate decisions.

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 what this tool does not do ('trains nothing, binds no version and spends nothing') and routes the agent to the alternatives that handle those steps (freeze_dataset_version, decide_approval) or to a human. This is explicit when/when-not guidance with named 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 already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a non-destructive local write. The description adds only the simulation-testing context; it discloses nothing about required permissions, uniqueness of names, or what happens on duplicate creation.

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 with verb, resource, and purpose; zero filler and nothing 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?

No output schema exists and the annotations cover the safety profile, so return-value explanation is not needed. However, for a resource-creation tool the description is sparse: it says nothing about how the persona relates to simulation runs or what identifying constraints apply.

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 examples given for name, tags, and description, so the schema carries the full parameter burden. The description adds no parameter meaning beyond what is already documented, which is the baseline-3 case.

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?

Clear verb + resource ('Create a new persona') plus a purpose qualifier ('for simulation testing'). It distinguishes itself from update_persona/get_persona/list_personas by the create verb, but does not contrast itself against related creation siblings such as create_agent or create_dataset.

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 phrase 'for simulation testing' faintly implies the context in which a persona is used, but there is no explicit when-to-use guidance, no prerequisites (e.g., persona must be linked to an agent), and no mention of alternatives such as update_persona.

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. The description adds real behavioral context beyond them: the content validation constraint (must be genuine dialogue, not system/config text) and the non-obvious side effect that auto-creating a prompt activates it before the run is logged. It does not cover permissions or rate limits, so 4 rather than 5.

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?

Front-loaded with the core action and the optimization prerequisite, then organized with clear labeled sections. Some overlap with the schema's own content requirement, but the length is defensible for a 12-parameter workflow tool.

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?

Covers purpose, prerequisite ordering, input-path selection, content validation rules, and the tool-grading rationale for the tool array parameters. No output schema exists, so return values need not be described; an agent has everything required to call this 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 the baseline is 3. The description adds value by explaining the interaction logic between parameters (the two prompt-sourcing paths and the purpose of toolCalls vs toolDefinitions) that the schema documents only per-field, not as a group.

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?

States a specific verb and resource ('Create a new run record') and immediately qualifies the source ('from a real user/AI dialogue transcript'). This distinguishes it from the read/list siblings (get_run, list_runs) and from the delete sibling without opening any 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?

Explicitly states the prerequisite for another tool ('You must upload runs before running trigger_optimization') and lays out the two mutually exclusive input paths (existing promptId vs auto-create with prompt/promptName/llmModel). When-to-use and alternatives are fully specified.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond that — it doesn't mention that the endpoint is registered outside this system, any verification/handshake, auth scope, or rate limits.

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 with zero filler. It is appropriately sized and wastes no words, though its brevity is part of why other dimensions are thin.

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 write tool with annotations covering the safety profile and a 100%-documented schema, the essentials are callable. However, nothing explains the superadmin-only customerId delegation, endpoint verification, or delivery behavior, leaving real gaps for a webhook-creation 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 schema already documents url, events (with a full event list), customerId (superadmin-only), and description. The description adds no parameter meaning beyond the schema, making 3 the correct baseline.

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?

States a specific verb (Create) and resource (webhook endpoint) plus its purpose ('for receiving event notifications'). An agent can tell it apart from delete_webhook/update_webhook/list_webhooks by the verb, though the description does not explicitly name those 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?

No guidance on when to create a webhook versus updating an existing one (update_webhook) or listing them (list_webhooks). The 'create' verb implies the intent, but nothing states prerequisites, alternatives, or when this is the right choice.

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 annotations (readOnlyHint=false, idempotentHint=false), it discloses that decisions are immutable and refused if already decided, that approving executes nothing and requires a runner to carry it, and the exact scope requirement plus audit stamping. This is exactly the kind of context annotations cannot convey.

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?

Front-loaded with the core action, then progressively adds finality, execution semantics, and auth scope, with no filler sentences. It is somewhat dense with clause-heavy sentences, but every sentence carries distinct 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 no output schema, the description correctly covers what happens on invocation (nothing executes; the approval is consumed) and the auth requirements. The remaining gap is the interpretation of the note parameter's downstream effect and any confirmation/return signal, which matters less given the tool's simple outcome.

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 80%, so the schema already documents projectId, approvalId, customerId, and note, and the enum covers state. The description adds the conceptual meaning of the decision (spend vs. production switch) but no per-parameter syntax or format detail, matching the baseline 3 for high-coverage schemas.

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 gives a specific verb pair (approve/decline) on a precisely bounded resource: 'one requested fine-tuning approval (training spend or the production switch)'. It also implicitly disambiguates from siblings like request_approval and list_pending_approvals by making clear this acts on an existing request rather than creating or listing one.

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 states clear preconditions ('a decision is final', already-decided approvals are refused, and write/admin/superadmin keys cannot call it), which tells the agent when this tool is and isn't valid. It doesn't explicitly name an alternative tool for constructing the approval in the first place, so it falls just short of a full when/when-not/alternatives statement.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety bar is partly covered. The description adds real value beyond that by enumerating exactly which collateral data is destroyed and asserting irreversibility, though it omits auth/permission requirements and any rate-limit or failed-deletion behavior.

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 short sentences, the destructive scope is front-loaded, and every clause carries information an agent needs (what is deleted, reversibility, tenancy scope). No padding or restatement of the tool title.

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?

There is no output schema, but for a delete tool the annotations supply the safety profile and the description supplies the cascade and tenancy scope, which is close to what an agent needs. It stops short of covering permission prerequisites or failure modes, leaving a small gap.

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 agentId, confirm, and customerId are already documented in the schema, which sets the baseline at 3. The description's 'Scoped to the authenticated customer' lightly reinforces the customerId semantics but adds no format or constraint detail 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?

States a specific verb (delete) and resource (agent), and unlike the bare name it enumerates the cascade: runs, run insights, prompt insights, prompt metrics. This clearly distinguishes it from delete_run, delete_user, and delete_webhook without opening any 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?

Conveys when the operation applies through scope ('Scoped to the authenticated customer') and the superadmin-only customerId note, but never states when not to use it or points to a safer alternative sibling. Usage is implied by the destructive/irreversible framing rather than stated.

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 annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description still adds real value beyond them: it enumerates exactly what is cascaded away (activities, runs, candidates, feedback) and confirms the operation is scoped to the authenticated customer.

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 short sentences, front-loaded with the permanent-delete action and cascade, then irreversibility, then scope. No filler sentences.

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 destructive tool with no output schema, the description covers action, cascade blast radius, irreversibility, and tenancy scope, and the required confirm flag is fully explained in the schema. Nothing an agent needs before invoking 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 processId, confirm, and customerId are already documented. The description adds only a mild scoping hint (authenticated customer) that loosely relates to customerId, but no format or constraint detail beyond the schema, so the 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?

States a specific verb (permanently delete) and resource (an optimization process plus its cascading records), which cleanly distinguishes it from the sibling stop_optimization and the other delete_* tools aimed at agents, runs, users, and webhooks.

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 by the framing: use this when the process and all its records must be removed for good, versus stopping it. However, the alternative sibling stop_optimization is never named or contrasted, so an agent must infer the choice between pausing and destroying.

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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description still adds genuine value beyond them: the deletion is permanent/irreversible and cascades to the run's insights, and it is scoped to the authenticated customer (with the superadmin customerId path noted in the schema).

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 short sentences, zero filler, and the destructive/permanent warning is front-loaded immediately after the action statement. Every sentence 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?

With annotations covering the safety profile and the schema fully describing all three parameters, the description supplies what is missing at the semantic level (irreversibility, insight cascade, customer scoping). No output schema exists, so return-value explanation is not required. Only minor gaps remain, such as whether the confirm flag or authorization prerequisites fail gracefully.

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 confirm, conversationId and customerId are already documented, giving baseline 3. The description adds only the customer-scoping context that loosely maps to customerId; it adds no format or constraint detail for conversationId or confirm.

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?

States a specific verb (permanently delete) and resource (a run), plus the cascade to its insights. 'Run' is clearly distinct from the delete_agent, delete_optimization, delete_user and delete_webhook siblings, so an agent can differentiate without opening the 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?

Usage is only implied: obviously for removing a run. There is no explicit when/when-not, no mention of alternatives such as get_run or list_runs, and no statement that this should be used only after review of the run. 'Scoped to the authenticated customer' is context but not invocation 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 destructiveHint=true and idempotentHint=false, but the description adds two pieces of non-derivable context: the operation is irreversible, and a business rule blocks deleting the last admin. It stops short of describing error surfaces or what happens to dependent resources.

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 short sentences, front-loaded with the verb and the destructive nature, with the guardrail last. No filler and nothing repeated from the schema.

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 destructive mutation with no output schema and full schema coverage, the description covers the essential risks: permanence, irreversibility, and the admin guardrail. Only error/response behavior is left unstated, which is a minor gap.

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 userId, confirm, and customerId are already fully documented, including the superadmin-only semantics of customerId. The description adds no parameter-level detail beyond the schema, so the baseline 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?

States a specific verb+resource ('Permanently delete a user account') and scopes it to the current customer. An agent can distinguish it from the many sibling delete_* tools (delete_agent, delete_run, delete_webhook) purely by resource.

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?

Gives clear context for invocation (user must be in the authenticated customer) and an explicit guardrail condition under which the call will be refused (last remaining admin). It does not name an alternative tool for softer removal, but no obvious sibling covers that case.

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 destructiveHint=true and readOnlyHint=false, covering the safety profile. The description adds nothing beyond that: no statement of irreversibility, no note on whether existing deliveries/history are removed, no auth requirements for the superadmin customerId path.

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 four-word phrase with zero waste and the action front-loaded. It is efficient, though its brevity is close to under-specification rather than true conciseness.

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 annotations carrying the destructive flag and the schema fully documenting both parameters, the minimum an agent needs is present. However, a delete tool of this kind would benefit from stating that removal is permanent and whether in-flight deliveries are affected, which 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 both webhookId and the superadmin-only customerId are documented in the schema itself. The description adds no format, scope, or side-effect detail about these parameters, so 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?

States a specific verb (Delete) and resource (webhook endpoint), so the action is unambiguous. It does not differentiate from sibling mutators like delete_agent, delete_run, or delete_user, but the resource noun is distinct enough that an agent can route to it.

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?

No guidance on when to use this versus update_webhook, get_webhook, or list_webhooks, and no prerequisites or warnings about confirming the target. The agent must infer everything from the name.

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 destructiveHint=true and readOnlyHint=false, so the agent knows this mutates state. The description adds useful context beyond that: the deployment status becomes 'dismissed' and the reason is persisted as learning feedback. It does not mention reversibility or required permissions, so it is adequate but not rich.

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 short sentences, front-loaded with the core action before the effect and the example utterances. No padding, though the trigger-phrase list is slightly redundant with the already-clear purpose statement.

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 mutating tool with no output schema and full annotation coverage, the description explains the action, its side effects, and the feedback-learning consequence. It omits what happens to the underlying PR/branch afterwards, but nothing critical to correct invocation 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 reason, customerId, and deploymentId, including the superadmin scoping note. The description adds little parameter-level meaning beyond restating that feedback is optional; 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?

States a specific verb (reject/dismiss) plus the target resource (a pending deployment/PR) and the effect (status set to dismissed). It is unambiguous what the tool does, though it does not explicitly differentiate itself from approval-flow siblings such as decide_approval or request_approval.

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 trigger phrases ('reject this PR', 'dismiss this deployment', 'I don't want this change') and the implicit constraint that the target must be pending, which aids invocation. However, it never names an alternative tool or explains when to use this versus decide_approval or request_approval, leaving routing 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description adds genuine behavioral context: it discloses a refusal policy for non-prompt-fixable failures and the two-part side effect (scenario creation + optional optimization). It does not mention permissions or whether the added scenario is reversible, but the key operational limits are surfaced.

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, front-loaded with the primary action, then the pipeline guidance, then the refusal rule. No filler and nothing repeated from the title or schema.

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?

No output schema exists, and the description does convey the outcome (scenario added; optimization optionally launched) and refusal conditions, which is most of what an agent needs. It stops short of describing what is returned (e.g., scenario or optimization identifiers) after success.

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 three parameters, including autoLaunch's default and the superadmin-only customerId. The description adds no format or constraint detail beyond what the schema provides, so 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?

States a specific verb+resource+effect: turning a failed run into a regression scenario on its owning agent, with an optional optimization launch. This is clearly distinguishable from add_regression_scenarios (generic bulk add) and get_worst_run (diagnosis only).

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 names the preceding sibling ('Pipe get_worst_run → fix_worst_run') and the condition that selects it, plus explicit refusal criteria (tool_config, model_limitation failures are not prompt-fixable). Both when-to-use and when-not-to-use are stated.

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 substantial context beyond annotations: irreversibility, the 409 abort-on-violation behavior, the blocked-for-training marking on diversity-floor failures, that only counts/coverage/hashes are returned (never examples), and the approve-scope stamping of the key id. The non-destructive annotation is consistent with creating a new version rather than deleting data, so 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?

Dense but front-loaded: purpose and scope lead, then failure semantics, then output and auth constraints. Every clause carries information an agent needs; nothing is padding.

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 mutation tool with no output schema, the description covers the mutation semantics, error behavior, partial-success case, what is returned, and the authorization scope. Nothing needed to call 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 description coverage is 100% and both parameters (datasetId, customerId) are documented in the schema, so the description adds no parameter-level detail. 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?

States a specific verb (Freeze) and resource (an immutable, numbered dataset version), and situates it distinctly from siblings like list_dataset_versions and bind_dataset_version by naming it as 'the one approval Datasets owns, and the version training binds to.' An agent can distinguish it without opening the 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?

Clear context: use it to create the immutable version training binds to, with the explicit caveat that it aborts on a violated leakage check and freezes-but-blocks versions under the diversity floor, plus a hard SCOPE: approve restriction naming which keys cannot call it. It does not explicitly name an alternative or a 'when not to use,' so it falls short of the top tier.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful-but-small fact of what is returned (org details, subscription plan), which partially compensates for the absent output schema, but says nothing about auth requirements or the superadmin impersonation behavior implied by customerId.

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?

One front-loaded sentence with no filler or redundancy. It is efficient, though the brevity leaves the gaps noted in other dimensions rather than the text being wasteful.

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 zero-required-parameter read tool with no output schema and full annotation coverage, the description telling the agent what comes back is adequate. It could clarify default scope (current account vs. impersonated customer) but nothing essential to invocation 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% and the single parameter's superadmin/act-on-behalf semantics are fully documented in the schema itself. The description adds no parameter meaning beyond that, so the 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?

Clear verb+resource ('Get account information') plus a preview of the returned content (organization details, subscription plan). It does not distinguish itself from adjacent read tools such as get_settings, get_usage, or get_converra_roi, so an agent must infer the difference.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives among the many get_* siblings. Nothing tells the agent when account info is the right call versus get_settings or get_usage; the agent is left to infer from the tool name alone.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context by specifying what items surface in the queue (undecided clusters, unverified training targets, unresolved members), which tells the agent what to expect from the call beyond the safety hints.

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?

Front-loaded with the resource definition, then the sibling exclusion, then the routing questions. It is appropriately sized and every sentence serves routing, though the trailing 'Answers:' clause slightly restates the purpose already stated.

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 read-only, 3-param, no-output-schema tool whose annotations carry the safety profile, the description covers purpose, contents, and sibling disambiguation adequately. Nothing essential to invoking it correctly is missing, though return shape or pagination behavior are left unstated.

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 limit, datasetId, and customerId are already fully documented in the schema (including the superadmin note on customerId). The description implies dataset scoping ('on this dataset') but adds no syntax or default details beyond the schema, so 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?

Specific verb+resource (get_adjudication_queue) plus an enumeration of exactly what the queue contains: clusters with no decision in force, unverified training targets, and unresolved members. It explicitly distinguishes itself from the sibling get_review_queue, 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?

Names the alternative it is not (get_review_queue = optimization PR queue) and states the questions it answers ('what needs adjudicating?', 'how much review is left?'), which routes the agent correctly. It gives clear positive usage and one exclusion, though it does not enumerate other sibling alternatives or broader when-not conditions.

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 and destructiveHint=false, so safety is covered. The description goes further by disclosing what the response actually contains (system prompt, role-family fields like instanceCount and siblings), which is meaningful because no output schema exists — though it does not flag that the system prompt may be sensitive 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?

Front-loaded with the core action and return contents, then a short explanation of why the role-family fields matter. Two sentences, no filler, though the closing SaaS-style example is slightly discursive for a retrieval tool.

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 no output schema, the description carries the burden of describing returns and does so at a reasonable level: named fields (agentType, customer, instanceCount, siblings) plus the generic categories of configuration and metadata. It is nearly complete, needing only the sensitive-data caveat or a note about the customerId superadmin path.

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% and both parameters (agentId, customerId with its superadmin-only note) are fully documented in the schema itself. The description adds no parameter-level detail — the word 'customer' appears only as a response field, not as guidance on the customerId parameter. 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?

States a specific verb (get) and resource (agent) and enumerates what comes back: system prompt, configuration, metadata, plus role-family fields. This distinguishes it from list_agents (plural listing) and get_agent_status (status only), though neither sibling is named 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 only implied — an agent can infer 'fetch full details' means use this rather than list_agents, but there is no explicit when-to-use statement, no exclusion against get_agent_status or analyze_agent, and no mention of prerequisites such as permissions needed to read a system prompt.

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, openWorldHint=false and destructiveHint=false, so the agent knows this is a safe, local read. The description adds only the shape of the returned data (optimization state, performance metrics) and nothing about permissions, currency of the snapshot, or rate limits.

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 with no filler; the key noun ('status of an agent') comes first and the payload detail follows. It earns its place but is minimal.

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 read-only getter with no output schema, the description gives a useful hint about returned fields, but it omits whether status is live or cached, and does not help disambiguate from get_agent. Adequate but with clear gaps.

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 both agentId and the superadmin-only customerId are fully documented in the schema. The description adds no further parameter meaning, which is the expected baseline when the schema does the heavy lifting.

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?

States a clear verb ('Get') plus resource ('agent status') and names the payload contents (optimization state, performance metrics), which helps an agent predict the response. However, it does not differentiate itself from the sibling get_agent or get_model_optimization_status, so the agent must guess which retrieval tool to pick.

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?

There is no statement of when to use this tool versus the many other 'get_*' retrieval siblings (get_agent, get_model_optimization_status, analyze_agent), nor any prerequisites or exclusions. Usage is only implied by the name.

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 cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral value by disclosing the staged return: progress feed while running, full comparison with recommendation when complete. This is the kind of lifecycle detail an agent needs to decide whether to re-poll.

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, zero filler, with the core action front-loaded and the return behavior following. Every clause carries 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?

There is no output schema, so the description must carry the return-value burden, and it does so at a high level (two distinct response states). Combined with annotations covering safety and a fully-documented schema, an agent can call it correctly; only the concrete fields of the comparison payload are left unspecified.

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 documented in the schema, including the jobId provenance and the superadmin-only customerId. The description adds nothing beyond the schema on parameter meaning, so the 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?

States a specific verb+resource: poll for benchmark job status and results. The 'benchmark' scope distinguishes it from the other status-getters (get_agent_status, get_simulation_status, get_model_optimization_status) in the sibling list. It stops short of explicitly naming a sibling, so it is clear but not maximally differentiated.

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 verb 'Poll' implies repeated invocation until completion, which is meaningful usage guidance for a status endpoint. However, it never states when to use this vs. alternatives or any prerequisite beyond the schema's 'job ID returned by benchmark_models' note. Context is implied rather than spelled out.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. Since no output schema exists, the description usefully carries the return-value burden by enumerating the summary contents. It adds nothing about the superadmin auth requirement for customerId or rate/cost behavior, keeping it short of a 5.

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?

Front-loaded with the core purpose in the first sentence, with supporting detail second. The trailing quoted questions are somewhat redundant with the listed contents but serve intent-matching, so the description stays tight overall.

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 two-parameter, zero-required, read-only aggregate tool with no output schema, the description supplies the return-value summary an agent would otherwise lack. What is missing is sibling disambiguation and any note on how `days`/`customerId` scope the result, but the essentials for calling it correctly are present.

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 both `days` (lookback, max 365) and `customerId` (superadmin only) fully documented inline. The description contributes nothing beyond the baseline about parameters, so the standard baseline 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?

States a specific resource and scope: a cumulative impact summary across all deployments, listing exactly what it contains (fixes shipped, issues resolved, failure reduction, before/after example). It is clear and concrete, but it never names a sibling (e.g. get_deployment_impact or get_fleet_overview) to differentiate this aggregate view from the per-deployment or fleet views.

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 quoted user questions ('how is Converra helping?', 'show me the impact') imply when the tool is appropriate, which is useful intent-matching. However there is no explicit when-not guidance, no mention of the alternatives (get_deployment_impact, get_fleet_intelligence), and no note that days/customerId change the scope of what is returned.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: reviewProgress is computed over every cluster while only the rows are paged, which prevents a caller from misreading paginated results as a scoped aggregate.

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, front-loaded with the primary return payload, then exclusions/alternatives, then the paging caveat. Dense but every clause carries information; slight verbosity in listing four member-resolution states inline.

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 no output schema, the description carries the return-shape burden and does so: it lists the cluster fields, names the excluded candidates, and explains paging vs aggregate scope. It does not mention the superadmin-only nature of customerId or auth requirements, a minor gap the schema partially covers.

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 baseline is 3 and the schema already documents limit/offset/datasetId/customerId/reviewState. The description still adds meaning by clarifying that limit/offset page only cluster rows and do not bound the reviewProgress aggregate, which the schema alone does not convey.

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?

States a specific verb+resource (get one dataset's cluster roll-up and review progress) and enumerates the returned fields: each behavior cluster's review state, the decision in force, and member resolution. It explicitly distinguishes itself from list_dataset_examples and get_review_case, so an agent can route without opening any 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?

Names alternatives with the condition that selects them: candidates are not returned here, so per-example admission goes to list_dataset_examples and single-cluster evidence goes to get_review_case. It lacks an explicit 'use this when' framing relative to the other review-queue siblings, but the routing guidance is concrete 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered, and the description usefully adds that results include parity verdicts, model IDs, a score definition and an estimated cost delta, plus the default grouping behavior. It stops short of describing ordering, volume of results per deployment, or how status values are computed.

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 plus a short question list, front-loaded with the core capability before the view-mode detail. The question examples are slightly redundant with the opening sentence but still earn their place as routing cues; overall tight 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 no output schema, the description correctly compensates by naming the payload contents (parity verdicts, model IDs, score definition, cost delta) and the default grouping. Pagination via cursor and the limit default live in the schema, but guidance on result ordering and how the eleven status values relate to the verdicts is left unstated.

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 every parameter including repo, view, limit, cursor and both enums is already documented in the schema. The description only restates the view='pr' grouping and the per-agent default, adding no syntax or behavioral detail beyond what the schema provides, so the baseline 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?

Names a specific capability — verifying whether deployed fixes/model swaps worked in production — and enumerates the concrete artifacts returned (parity verdicts, model IDs, score definition, cost delta). It also distinguishes its two operating modes (per-agent default vs. PR-grouped), which lets an agent separate it from nearby siblings like get_pr_context and get_verification_evidence.

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 three quoted questions ('did my fixes work?', 'what PR changed this?', 'show me PR impact') give clear invocation contexts tied to the two view modes. However, it never names an alternative tool or states when NOT to use it, so an agent comparing it against get_pr_context or get_production_test must infer the boundary itself.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses that gate elements appear as names and outcomes only (a truncation/limitation) and where to get the fuller detail.

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?

Front-loaded with the core payload description, then the gate limitation and alternative. Dense enumeration of contents but each clause carries information; no filler sentences.

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?

No output schema exists, so the description must convey return contents, and it does so in detail (journey, dataset version, progress, job facts, approvals), plus the partial-coverage caveat for gates. Combined with read-only annotations, an agent has enough to call it 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%, with both projectId (from list_fine_tuning_projects) and customerId (superadmin only) documented in the schema itself. The description adds no additional parameter syntax or constraint, so the baseline 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?

Clear verb (get) and resource (fine-tuning project), and the description specifies the composite contents returned: the eight-step journey, bound dataset version, review progress, training-job facts, and approvals. It differentiates from get_gate_result for the gate portion, but does not distinguish itself from siblings like get_training_job or list_fine_tuning_projects.

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 routes the agent to an alternative: 'use get_gate_result for one verdict element by element.' That is a concrete when-to-use-another-tool instruction. It lacks guidance on when to prefer this over other project-scoped getters, so not complete.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without description help. The description usefully adds that results are ranked by impact and include before/after counts and fix badges, which is real behavioral context. It stops short of describing pagination, ordering semantics, or whether the badges are computed live versus cached.

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 content is front-loaded: the first sentence states the resource and its key fields, and the badge/count detail follows. The three example questions are slightly redundant with each other but efficiently communicate intent. No filler sentences.

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?

There is no output schema, so the description must carry the return-value burden, and it does reasonably well by listing failure counts, business-impact descriptions, and fix-verification badges. Combined with the read-only annotations and 100% param coverage, an agent has enough to invoke it correctly, though ordering/pagination and fleet-scope framing remain unspecified.

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 a single documented parameter (customerId, noted as Converra-superadmin only), so the schema carries the parameter semantics fully. The description adds nothing about the parameter, which is the baseline 3 case when the schema does all the work.

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 names a specific resource (fleet-level failure patterns) and enumerates what it contains: business impact descriptions, fix verification status, before/after failure counts, and Improved/Fixed badges. This gives an agent a concrete picture of the tool's output. However, it never distinguishes itself from close siblings like get_fleet_overview, get_fleet_timeline, or get_insights, which an agent could easily confuse it with.

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 'Answers:' framing implies usage contexts ('what are the biggest issues hurting my fleet?', 'what has Converra improved?'), which gives implicit guidance on when to reach for it. But there is no explicit when-to-use-vs-alternatives statement, no mention of when NOT to use it, and no routing to get_fleet_overview/get_fleet_timeline/get_insights despite them being obvious contenders.

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, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description adds real behavioral value by enumerating the returned dataset (scores, run counts, failure rates, deployment stats), which matters since no output schema exists; it does not mention pagination or volume limits.

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 payload summary is front-loaded in the first sentence and the example questions are compact. The three-question list is slightly redundant with the opening statement but still earns its place by clarifying intent.

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 no output schema present, the description correctly takes on the burden of describing the return contents, and the annotations cover the safety profile. The only meaningful gap is that it doesn't distinguish this aggregate view from the other fleet-level tools an agent could pick instead.

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 both parameters (sortBy with its enum and customerId) are already fully documented in the schema. The description contributes nothing about sorting semantics or the superadmin scoping requirement, so the 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?

The description states a specific verb+resource ('fleet-level dashboard showing all agents') and enumerates the metrics it exposes (performance scores, run counts, failure rates, deployment stats). It positions itself as the 'entry point' for fleet health, which helps, but it never names or contrasts with near-neighbors like get_fleet_intelligence, get_fleet_timeline, or list_agents.

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?

Concrete usage context is provided via the target questions it answers ('how are all my agents doing?', 'which agent needs attention?', 'what has Converra fixed?'), which clearly frames the when-to-use scenario. There are no explicit exclusions or named alternatives, so an agent must still infer that per-agent deep dives belong to get_agent/analyze_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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world). The description adds substantive context beyond them: the specific aggregates returned (daily avg score, run count, contributing-agent count) and the fact that deployment markers are unioned across agents.

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 tight sentences, front-loaded with the scope, then the usage trigger, then the return contents. No filler and every sentence carries 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?

No output schema exists, but the description compensates by enumerating the returned fields, so an agent knows what it gets back. It leaves minor gaps (e.g. how hours/missing days or empty fleets are handled) but is otherwise complete for a two-param read 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 both parameters (days with default/max, customerId superadmin-only) are fully documented in the schema. The description adds nothing about parameter behavior, matching the baseline for schema-documented params.

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?

States a specific verb+resource (run-weighted score timeline aggregated across ALL agents in the fleet) and immediately differentiates from the per-agent sibling by contrasting fleet-wide vs 'one agent at a time'. An agent can distinguish it from get_score_timeline or get_agent without opening a 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?

Gives a clear when-to-use trigger ('how is the whole fleet trending over time?') and an implied exclusion of the single-agent case. It does not name the exact alternative tool (e.g. get_score_timeline), so routing is inferred rather than explicit.

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 carry the read-only safety profile, so the description earns credit for what it adds beyond them: the verdict is minted externally by the gate harness, this tool performs no computation of its own, and dev dry runs are labelled and must not be treated as acceptance evidence. That provenance/trust caveat is genuinely non-obvious behavioral context not found in 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?

Three compact sentences, front-loaded with what is returned before the provenance caveat. Every sentence carries weight, though 'minted outside the app by the gate harness' is slightly ornate phrasing where plainer wording would serve an agent just as well.

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 no output schema, the description usefully compensates by describing the return shape (per-element verdict plus scalar measurements) and flags the trust distinction between dry-run and acceptance verdicts. It is largely complete for a read-only lookup; only the sibling routing and verdict-availability behavior are left 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 description coverage is 100%, including verdictId's default resolution to the protected acceptance verdict, so the schema does the heavy lifting and the baseline is 3. The description adds only the structural hint that the result is per-element with scalar measurements; it offers no extra detail on projectId, jobId, or customerId scoping.

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?

Specific verb+resource: it returns 'one frozen-gate verdict, element by element, with each element's own scalar measurements,' which is a concrete deliverable an agent can recognize. It implicitly separates itself from the write-side sibling record_gate_result by stating 'this only reads what was recorded,' but it never names a sibling outright, so the differentiation is inferred rather than explicit.

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 the retrieval context (reading an already-minted verdict) but never states when to reach for this tool versus get_verification_evidence, get_adjudication_queue, or record_gate_result. The dry-run caveat ('never acceptance evidence and is labelled as such') is useful context but is a data caveat, not a when-to-use rule.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that results are 'aggregated' and derived from run data, which hints at computed rather than raw values, but says nothing about staleness, caching, or whether a refresh is needed to see new insights.

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 efficient sentence with no filler, and the core noun (aggregated performance insights) is front-loaded. It is arguably too terse given the crowded sibling space, but there is no wasted text.

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 read-only aggregation tool with no output schema and fully documented parameters, the minimum is met by the annotations plus schema. Still missing is the relationship to refresh_agent_insights / batch_regenerate_insights and any indication of what the aggregate contains, which an agent would need to choose correctly among the many insight siblings.

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%: agentId, days (with default 30), and the superadmin-only customerId are all documented in the schema. The description adds no extra parameter semantics, so 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?

States a specific verb and resource ('Get aggregated performance insights') scoped to 'an agent' derived from 'run data', which is clearer than the bare title. However it never differentiates itself from close siblings like get_run_insights, refresh_agent_insights, or get_fleet_intelligence, leaving the agent to infer the level of aggregation.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_run_insights (per-run) or refresh_agent_insights (to regenerate). The agent must guess which insight-fetching tool to pick from a list of several.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description usefully adds that output is a generated, stack-tailored guide containing exact code, packages, and configuration. It does not disclose anything about how the guide is generated or its size/format, keeping it short of a 5.

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, front-loaded with the purpose and then the input/output contract; no filler and every clause 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?

With no output schema, the description compensates by naming the deliverables (code, packages, configuration). Combined with full parameter coverage and a read-only annotation profile, an agent has enough to call it, though it could say more about output shape.

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 each parameter already carries rich examples, so the schema does the heavy lifting. The description only restates that 'stack' should describe your tech stack, adding no syntax or constraint detail 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?

States a specific verb+resource ('Get a step-by-step integration guide') scoped to connecting an LLM app to Converra, and it is readily distinguishable from siblings like verify_integration and list_integrations. An agent knows exactly what this returns.

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 implies the usage pattern (describe your stack, receive tailored code/packages/config) but never states when to reach for this versus verify_integration or list_integrations, nor any prerequisites or exclusions. Usage is inferable but not guided.

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 it is safe and read-only. The description adds important behavioral context beyond annotations: it returns interim progress while running and a full report when complete, indicating the response changes over the job lifecycle. It does not cover rate limits or polling cadence, but provides solid extra value.

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 zero waste, front-loading the action and then clarifying the return behavior. Every sentence 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 read-only status tool with no output schema, the description summarizes what is returned at different stages. It could mention more about authentication or polling strategy, but given the rich annotations and complete schema descriptions, it is largely sufficient.

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 both jobId and customerId are already documented in the schema. The description adds no parameter-specific semantics beyond what is already provided, making the baseline of 3 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?

States a specific verb ('Poll') and resource ('model optimization job status and results'), clearly describing the tool's function. It does not explicitly distinguish itself from sibling tools like get_optimization_details, but the name and description together are unambiguous.

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 word 'Poll' implies the tool is used after starting an optimization job to check on it, but there is no explicit guidance on when to use this versus get_optimization_details or other status-related siblings, nor any stated exclusions.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without the description. The description adds value by naming the content categories returned and the includeActivities toggle behavior implied by the schema, but says nothing about authorization requirements or result size. Adequate, not rich.

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 tight sentence with the resource front-loaded and no filler. It is efficient, though it could have spent one clause on when to prefer it over sibling readers instead of purely enumerating return contents.

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 read-only detail fetcher with full schema coverage and annotations covering the safety profile, the description supplies the one thing the structured fields cannot: what the response contains. The lack of any usage routing is the only real gap, and there is no output schema to explain returns.

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 processId, customerId, and includeActivities are already fully documented in the schema, making 3 the correct baseline. The description's mention of 'activities' loosely corresponds to includeActivities but adds no format or default information 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?

Specific verb (get) plus resource (optimization run details) and an enumeration of the payload (variants, activities, results), which tells an agent exactly what comes back. It does not explicitly differentiate itself from close siblings like get_variant_details or get_model_optimization_status, but the scope is unmistakable.

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?

There is no statement of when to reach for this tool versus list_optimizations, get_variant_details, or get_model_optimization_status, and no preconditions are given. Usage is only loosely implied by the word 'details', which is weak given how many overlapping read tools exist in this namespace.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that results include description and usage stats, but says nothing about authorization scope (the superadmin customerId path lives only in the schema) or any limits.

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 naming the operation, the scoping ('specific'), and the payload. No filler, no restatement of the title.

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 two-parameter read tool with full schema coverage and no output schema, the description covers what is retrieved and is safe to call. It stops short of tying the tool to a workflow (e.g. after list_personas), which is the only real gap.

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 both parameters are already documented, including the superadmin-only semantics of customerId. The description adds no parameter-level meaning beyond what the schema provides, which is the expected baseline.

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?

States a specific verb (get) and resource (persona), and 'full details ... including its description and usage stats' tells the agent what comes back. It does not explicitly contrast with list_personas or get_agent, but the word 'specific' implicitly signals single-record retrieval.

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?

There is no when-to-use guidance and no named alternative. With list_personas and update_persona in the sibling set, the agent must infer on its own that this is the read-one-record counterpart, and nothing explains when persona details are needed versus agent details.

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 and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral value by enumerating the return payload (simulation evidence, before/after example, metric breakdown, review guidance, previous feedback, failure patterns), letting the agent anticipate output despite there being no output schema.

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 opening sentence front-loads the core purpose, and the long enumerated list of returned sections is dense but earns its place by replacing a missing output schema. The trailing question list is slightly redundant but useful for intent matching.

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 read-only retrieval tool with no output schema, the description compensates by spelling out exactly what the briefing contains and what questions it answers. Auth nuance is left to the schema's customerId note, so coverage is strong though not exhaustive.

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 deploymentId, customerId and includeDiff. The description adds no parameter-level detail beyond what the schema provides, so the 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?

States a specific verb+resource ('Get PR Context') and immediately names the scope: a comprehensive reviewer briefing for a specific deployment/PR. The enumerated contents (issues fixed, what changed, simulation evidence, regression results, etc.) make it unambiguous which sibling this is versus read tools like get_review_case or get_verification_evidence.

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 concrete user intents ('tell me about this PR', 'should I merge this?', 'what does this fix?') and stresses 'one call', implying it consolidates what would otherwise be multiple lookups. It stops short of naming an alternative tool or an explicit when-not condition, so it is clear context without exclusions.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description contributes the return facets (arm counts, decision state), but says nothing about freshness, cost, or errors for a missing test ID. Adds some value over annotations, but not rich 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?

A single front-loaded sentence with no filler; the operation and its output facets come first. It is efficient, though it is so brief that it omits any routing or caveat 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 no output schema, the description does the right thing by enumerating what comes back (status, arm counts, decision state). Combined with full schema coverage and read-only annotations, an agent has enough to call this correctly, though sibling disambiguation is still 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% for both parameters, including the '(Converra superadmin only)' qualifier on customerId, so the schema carries the burden. The description's phrase 'production A/B test' loosely maps to productionTestId but adds no syntax, format, or scoping detail 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?

States a specific verb ('Get') and resource ('production A/B test') plus the three data facets it returns (status, arm counts, decision state). This distinguishes it from the write-oriented siblings promote_production_test, rollback_production_test, and start_production_test, though it never names an alternative 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?

There is no when-to-use guidance, no prerequisites, and no mention of related tools such as get_variant_details or get_benchmark_status. The agent must infer that this is the read counterpart to the production-test lifecycle tools.

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 readOnly, non-destructive, and non-open-world, so the safety profile is covered. The description adds useful content-shape context (source tracking indicates synthetic vs production-reproduction origin) but says nothing about auth needs, rate limits, or behavior 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?

Two sentences, front-loaded with what is retrieved and what is returned, with no filler. Slightly dense but every clause carries 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?

For a read tool with no output schema, the description adequately signals what is returned (scenarios, source tracking, baseline scores) and the annotations carry the safety profile. Auth and response-shape specifics remain thin, but nothing critical for correct invocation 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 both agentId and the superadmin-restricted customerId are already documented in the schema. The description adds no syntax, format, or constraint detail beyond that baseline.

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?

States a specific verb (Get) and resource (regression test suite for an agent), then enumerates the payload contents (scenario details, source tracking, baseline scores). It implicitly separates itself from add_regression_scenarios and regression_test by being the read path, but no sibling is named 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?

"Use this to understand what scenarios guard against regressions during optimization" gives a clear when-to-use context, but offers no exclusions or named alternatives (e.g. vs regression_test or get_production_test).

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 establish this is a safe, non-destructive read, so the bar is lower. The description adds real value anyway by disclosing the response shape (verification, decision history, members) and the paging behavior — members are paged because a cluster can hold hundreds — which is the kind of behavioral detail annotations do not supply.

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 resource and its contents are front-loaded in the first sentence, with a short second sentence justifying paging. It is dense but each clause names a distinct field of the returned case, so little is wasted.

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 no output schema, the description carries the return-value burden and does so by enumerating the case's components and explaining the paging constraint. The main remaining gap is the absence of usage/routing context for a tool whose id comes from a queue or dataset.

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 clusterId, customerId, and memberLimit are already documented, including defaults and max. The description only loosely echoes 'a page of members', adding no syntax or format detail beyond the schema, so 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?

The description clearly identifies the resource and its scope: one cluster's review case, enumerating what the case contains (representative candidate, finding, evidence, training target, verification, decision history, members). It is distinguishable from get_review_queue and get_adjudication_queue by being singular and case-focused, though it never states the retrieving verb explicitly or names those 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?

There is no when-to-use guidance or mention of alternatives. An agent is not told to call this after get_adjudication_queue or instead of get_review_queue; the only routing hint (clusterId comes from get_adjudication_queue or get_dataset) lives in the schema, not the description.

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 and destructiveHint=false, so the safety profile is covered. The description usefully adds the ranking criteria (severity, simulation evidence strength, wait time, run volume), but says nothing about pagination, limits, or freshness beyond what the schema states.

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?

Front-loads the resource and scope in the first sentence, with ranking detail second. The trailing list of paraphrased user questions is somewhat redundant filler, but overall it is tight.

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 no output schema, the description carries the burden of describing returns and does so — pending PRs/deployments, their priority ordering, and what the ordering is based on. Missing only edge behavior like what happens when the queue is empty or how items expire.

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% and all three parameters (limit, agentId, customerId) are documented in the schema, including defaults, maxima, and the superadmin restriction. The description adds no parameter information, so 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?

Names a specific resource and scope: a prioritized list of pending optimization PRs/deployments needing human review. Clear verb+resource, but it does not distinguish itself from nearby siblings like list_pending_approvals, get_adjudication_queue, or get_review_case.

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 quoted user questions ('what should I review?', 'any pending PRs?') imply when to reach for it, but no explicit when-not conditions or alternative tools (e.g. get_adjudication_queue vs. list_pending_approvals) are offered.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that insights are part of the payload, but that is also stated in the schema for includeInsights, so it contributes little beyond structured fields; return shape and any permission notes are absent.

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, zero filler, with the core action and payload front-loaded and the lookup mechanism immediately after. Every clause carries 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?

For a read-only getter with 100% schema coverage and no output schema, the description covers action, payload, and lookup key. The one soft spot is that no parameter is required, so an agent could call with zero arguments; the 'look up by X or Y' phrasing mitigates this but does not spell out the either/or requirement.

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 all four parameters are already documented, including the LangSmith/Langfuse example and the conversationId-preferred rule. The description only restates those two lookup modes, adding no syntax or format detail beyond the schema — 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?

States a specific verb and resource ('Get full details of a specific run') plus the scope of what comes back ('including insights'). It clarifies the two lookup keys, which helps separate it from list_runs and the insight-specific siblings, but it never names an alternative tool 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?

It implies when the tool applies ('Look up by Converra run ID or by external session ID') and effectively tells the agent that one of the two identifiers is needed. However, it gives no guidance on when to prefer this over get_run_insights, get_run_step_diagnosis, or list_runs, and no exclusions.

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, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the call returns a sequential 'next' question and the exact publication/question hashes needed for a downstream write. It does not state whether fetching advances/cursors the question or what happens when none remain.

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 tight sentences with no filler, front-loading what the tool returns and following with the downstream requirement. Every clause carries 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 no output schema, the description does the work of describing the return value (the question plus the publication and question hashes). It stops short of explaining the response shape or the exhausted-queue case, which for a read tool is a minor gap.

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 conversationId and customerId both documented in the schema (including the superadmin-only constraint). The description adds no additional parameter meaning, so the 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?

The description gives a specific verb (Get) and resource (the next canonical evidence-bound calibration question for a run), which is far more precise than the name alone. It does not explicitly name the complementary sibling record_run_calibration_review, so the get-vs-record distinction is left to the reader.

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 phrase 'required to record the answer' implies the calling context (fetch hashes, then record), but there is no explicit when-to-use statement or exclusion relative to siblings like get_review_case or get_review_queue. Usage must be inferred from the workflow hint.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured fields. The description's only added behavioral signal is the word 'bounded', hinting at capped/summarized context, but it never explains what bounds are applied, whether results are truncated, or how the optional responderRunId changes evidence selection (that detail lives only in the schema).

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 with a dense but purposeful list; no filler or restated title. The list of bundled artifacts is long enough to be slightly heavy to parse, but every item conveys distinct content.

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 no output schema, the description does the work of enumerating return contents, which is genuinely useful. It remains incomplete on the 'bounded' contract (size limits, truncation, ordering) and gives no guidance on how the context should be consumed for the review decision, so an agent has the intent but not the full operational picture.

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% and all three parameters carry their own descriptions, including the nuanced responderRunId behavior and the superadmin-only customerId. The description adds no parameter-level meaning beyond the schema, so the baseline 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 states a specific verb ('Get') and resource ('grounding context for a run finding') and enumerates exactly what is bundled: transcript, latest insight, prompt snapshot status, architecture context, and dismissed feedback. That enumeration clearly separates it from siblings like get_run_insights or get_run_step_diagnosis, though it never names those alternatives 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?

The phrase 'for reviewing a run finding' implies the usage context, and the tool is evidently a read-side companion to the review flow. However, there is no explicit when-to-use versus when-not guidance, no mention of prerequisites, and no routing to sibling tools such as preview_run_finding_prompt_diff or get_run_calibration_review that an agent might confuse it with.

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 and destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds one genuinely useful behavioral fact beyond annotations — that the response carries the activePublication CAS target needed for an external generation write — but omits auth/superadmin scoping behavior and any pagination or size characteristics.

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 that wastes no words and leads with the core action. It is arguably too compressed for the payload it promises, but every clause 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?

No output schema exists, yet the description compensates by naming the return contents (metrics, findings, terminal status, CAS target). With annotations covering the safety profile and the schema covering all parameters, the definition is close to complete; only the sibling-routing and auth context are 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 all three parameters (sessionId, customerId, conversationId) are already fully documented in the schema, including the sessionId-vs-conversationId precedence rule. The description adds nothing about parameter usage, so the 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?

States a specific verb and resource ('Get detailed insights for a specific run') and enumerates the payload (metrics, findings, terminal status, CAS target). It is clear what it does, but it never distinguishes itself from close siblings like get_insights, get_run, or get_run_finding_context, so an agent must infer the boundary.

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?

There is no when-to-use guidance, no prerequisites, and no routing to alternatives among the many get_* siblings. The mention that the CAS target is 'required for an external generation write' implies a downstream step but never names publish_external_run_insight_generation or says when to call this tool instead of get_run.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context by disclosing the data-source fallback (trace data when available, otherwise transcript-based diagnosis), which affects reliability and completeness of results.

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 tight sentences, front-loaded with the core purpose and followed by outputs and availability caveat. No filler or redundant restatement of the title.

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 no output schema, the description usefully summarizes what the diagnosis returns and notes the data-source fallback, which is enough for an agent to call it correctly. The only gap is the absence of guidance against related diagnosis/insight siblings.

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 both parameters (customerId superadmin note and conversationId) are fully documented in the schema. The description adds no additional parameter meaning beyond what the schema provides, so 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?

The description states a specific verb and resource ('get step-level failure diagnosis for a run') and enumerates the concrete outputs (first failed step, cascade effects, root cause, per-turn timeline). It implicitly differentiates from the sibling get_step_failure_aggregation by being per-run and diagnostic rather than aggregate, but never names that sibling 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?

It states availability ('Available for all runs') and a fallback mode, which implies usage context, but gives no explicit when-to-use vs. alternatives despite close siblings like get_step_failure_aggregation, get_run_insights, and get_run. The agent must infer which diagnosis tool to pick.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral content beyond that: the data is daily-granular and the timeline includes deployment markers tied to merges, which tells the agent what the output will let it reason about.

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?

Front-loaded with what the tool returns, then a compact set of example prompts. Every sentence earns its place; no filler or restatement of the title.

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 read-only analytics tool with a fully documented schema and no output schema, the description covers what is returned (daily scores, deployment markers) and the questions it answers. An agent has enough to select and call it 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%, with defaults and max documented for 'days' and the superadmin-only note on 'customerId'. The description only restates 'over a date range' and adds no format or scoping nuance beyond the schema, so the 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?

States a specific verb+resource ('daily score timeline for an agent over a date range') plus an extra distinguishing feature (deployment markers for merged PRs). It is clearly an agent-scoped read, which implicitly distinguishes it from the fleet-level sibling get_fleet_timeline, though it never names that sibling.

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 three quoted example questions ('did overall performance improve after our fixes?', 'show me the score trend') give concrete context for when to reach for this tool. There is no explicit when-not guidance or named alternative (e.g. get_deployment_impact, get_fleet_timeline), so it stops short of a 5.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds no extra behavioral context such as whose settings are returned by default, whether the customerId impersonation changes scope, or any auth/permission note beyond what the schema states.

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 with no filler or repetition. It is appropriately sized for a simple read tool, though it stops short of adding the structural pointers (scope, defaults) that would make it maximally useful.

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?

There is no output schema, so the description should ideally indicate what 'settings' contains; it does so only at a high level ('general preferences and optimization configuration'). Adequate for a one-parameter read tool with full annotation and schema coverage, but not rich.

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 the sole parameter (customerId) is fully documented as superadmin-only acting-on-behalf-of. The description contributes nothing about the parameter, so the schema carries the load and the 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?

States a specific verb (get) and resource (account settings) and even enumerates the two content areas: general preferences and optimization configuration. It is distinguishable from update_settings by the read verb, though it does not explicitly differentiate itself from the similarly named get_account sibling.

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?

No when-to-use guidance, no prerequisites, and no mention of the obvious alternative update_settings for modifying these settings. The agent must infer usage entirely from the name.

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, destructiveHint=false and openWorldHint=false, so the safe-read profile is covered structurally. The description adds genuine behavioral context by framing the resource as an async job that must be polled for completion, implying repeated idempotent calls and possibly incomplete results. It does not describe failure/expiry states or what the returned result payload looks like, so the addition is real but modest.

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 filler, purpose stated first and the usage trigger second. Every sentence 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 read-only polling getter with full schema coverage and no output schema, the description covers what the tool does and when to call it. It could mention what happens while the job is still running (e.g., status values) but nothing essential to invoking 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 jobId and customerId are already documented, including that jobId comes from simulate_agent/simulate_ab_test and that customerId is superadmin-only. The description adds no parameter-level detail beyond the schema, so the 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?

States a specific verb and resource (get status/results of an async simulation job) and ties the resource to the two sibling tools that create such jobs. An agent can tell it apart from other status getters like get_agent_status or get_benchmark_status, though the differentiation rests on the referenced simulate_* calls rather than an explicit contrast.

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?

"Use this to poll for completion after calling simulate_agent or simulate_ab_test" gives clear, actionable context for when to invoke it. There is no explicit when-not guidance, but the polling framing is specific enough that an agent knows the trigger condition.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds useful output-content context (what categories are returned) but says nothing about permissions, aggregation window, or cost, so the marginal behavior disclosure is moderate.

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, front-loaded with the core purpose, then the returned content, then usage scenarios. No filler, though the example-question sentence is somewhat verbose relative to the information it adds.

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?

There is no output schema, so the description carries the burden of describing return values, which it does by listing the four content categories. Combined with the annotation coverage for safety, this is largely complete; only the lack of any note on aggregation scope/time window or auth implications leaves a minor gap.

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%: agentId and the superadmin-only customerId are both documented in the schema. The description adds no parameter-level meaning (no scope semantics for agentId, no mention of customerId impersonation), so the baseline 3 for schema-documented params 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?

States a specific verb and resource ('Get ... step failure patterns') with clear scope ('fleet-level ... across all diagnosed runs for an agent'), and enumerates the displayed content (failure types, root causes, agent-type breakdown, suggestions). It does not explicitly differentiate itself from adjacent analytic siblings such as get_fleet_intelligence, get_run_step_diagnosis, or get_insights, so it lands just below a 5.

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?

Gives explicit use-case framing via example questions ('what are my top failure patterns?', 'which agent steps are causing the most failures?'), which tells the agent when to reach for it. However, it names no alternatives or exclusions, so the agent must infer it versus other failure/analysis tools.