Converra

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), it discloses genuinely non-obvious behavior: propagation to all FUTURE generations for the agent, default immediate forced regeneration of the current run, and delayed pickup by other runs. This is exactly the kind of richer context annotations cannot 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?

The core action is front-loaded in the first sentence, followed by scope and default side effect. Four sentences with little waste, though the final sentence slightly repeats the propagation point made earlier.

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 nested params and no output schema, the description adequately covers purpose, attachment scope, and side effects. It does not describe the response shape or permission requirements (e.g. the customerId superadmin path), leaving 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 the schema already documents all 9 parameters, giving a baseline of 3. The description adds only the default regeneration behavior, which is already stated in the triggerRegeneration schema text, so it does not meaningfully extend parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('Record disagreement with a run insight') and immediately clarifies the non-obvious scope: feedback attaches to the owning agent, not the run. This distinguishes it from sibling tools like add_optimization_feedback and regenerate_run_insights by explaining the target of the correction.

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 clearly frames the usage context (disagreeing with an insight) and explains the default side effect, but it never explicitly names an alternative tool or states when-not to use it — e.g. vs regenerate_run_insights or refresh_agent_insights. Context is clear without explicit alternatives/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 only declare readOnlyHint=false and destructiveHint=false, so the description carries the meaningful burden and does add value: it discloses that feedback is stored per-agent and 'propagated as context to future optimizations' — a side effect that persists beyond the call. It doesn't cover failure modes or what happens when neither rating nor comment is supplied.

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, no waste: the action is front-loaded, then the persistence/propagation behavior, then the enum guidance. 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 7-parameter mutation with no output schema, the description covers purpose, storage behavior, and the key enum semantics. It omits edge-case guidance such as whether rating and comment may be combined or omitted, and does not mention the superadmin-only customerId parameter that the schema documents.

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, but the description goes beyond the schema by explaining the intent behind each feedbackType value with use-case examples, which helps the agent pick the right enum. It adds little for the remaining parameters (agentId, comment, variantId, optimizationId, customerId).

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 ('Add feedback ... on an optimization result') and scopes the target to optimization results, which separates it from the sibling add_insight_feedback. An agent can tell what it does and what it acts on 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?

It gives explicit when-to-use guidance for the three feedbackType values, with concrete examples ('never remove the disclaimer' for constraint, 'focus on reducing hallucination' for direction). It does not explicitly rule out or route to the sibling add_insight_feedback, so the alternative-selection guidance is incomplete.

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 mark this as a non-read, non-destructive mutation, and the description adds genuinely new behavior: writes are appended and existing scenarios are preserved, which tells the agent this is additive rather than a replace/overwrite. It does not describe any permission requirements or whether the change is reversible/undoable.

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 action and target, then usage, then the append guarantee. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an additive mutation with full schema coverage and annotations declaring the safety profile, the description supplies the key missing piece (append semantics and a purpose for the added scenarios). An output schema does not exist, so return values are not needed; the only minor gap is no note on limits or whether added scenarios take effect immediately.

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 3 parameters, so the schema already documents agentId, scenarios, and the nested scenario fields including isSafetyCritical. The description adds no syntax, format, size limits, or batching guidance 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 ('Add custom regression test scenarios') and scopes the target ('an agent's existing golden suite'), which separates it from suite-creation or read paths. It does not name the sibling get_regression_suite explicitly, so an agent must infer the read/write split from the sibling list.

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 gives a clear use case ('strengthen the regression suite with scenarios targeting specific behaviors') plus concrete examples (human escalation, multi-language, support routing). There is no when-not guidance and no explicit pointer to the read sibling for reviewing an existing suite.

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 one behavioral fact beyond that – analysis is performed statically, without running simulations – which signals low cost and no execution side effects. It says nothing about processing time, limits, or what happens when optional params are omitted, so the added context is thin.

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, the outputs, and the key constraint with zero filler. Nothing is redundant with the title 'Analyze Agent' and no sentence 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 some of the return-value burden, and it does indicate the shape of results (weaknesses plus improvement recommendations). With only 3 params at full schema coverage, the inputs are well covered. It is close to complete, though it could clarify the difference between the static analysis output and metric-enriched output when promptId is supplied.

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 (prompt, promptId, customerId) are already fully documented in the schema, including the superadmin restriction on customerId. The description adds no additional semantics about parameter formats, interactions, or defaults. Baseline 3 is appropriate 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?

The description names a specific verb ('analyze') and resource ('an agent's system prompt structure') and states the outputs ('weaknesses', 'improvement recommendations'). It explicitly distinguishes itself from 'simulate_agent' by noting it works 'without running simulations'. It does not differentiate from other analysis-adjacent siblings such as refresh_agent_analysis or get_agent_status, so it falls 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?

The phrase 'without running simulations' implies usage via contrast with simulate_agent, giving the agent a useful implicit routing cue. However, there is no explicit 'use this when' statement, no exclusions against the many other agent tools (get_agent, refresh_agent_analysis), and no prerequisites for the optional historical-metrics path. Usage is implied 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds useful context by naming exactly what is altered: 'replace the original agent prompt content.' It does not disclose reversibility, rollback options, or approval requirements, 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?

A single front-loaded sentence with zero filler; the action and its effect are stated immediately. Efficient, though a little terse given the destructive nature of the operation.

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 core purpose and effect are conveyed, and annotations cover the safety flag. However, an agent would benefit from knowing about irreversibility or prerequisite steps, which are absent.

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 three parameters (processId, variantId, customerId) are already fully documented. The description reinforces the 'winning variant' default for variantId but adds no new syntax or format detail. Baseline 3 applies 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 specific verb pair (apply/deploy) and resource (winning variant) plus the concrete effect: replacing the original agent prompt content. This clearly separates it from validate_variant and get_variant_details, though it does not name those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance, no prerequisite (e.g., that a variant must first be validated or a process completed), and no mention of alternatives. The agent must infer that this is the terminal step after a variant wins.

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=true, so the mutation/overwrite profile is disclosed structurally. The description adds that a progress summary is returned and frames the bulk-fix/refresh use case, but the overwrite semantics ('existing insights overwritten on success') live only in the schema, not the description. Adequate additional context, 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 purpose and followed by usage and return behavior. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a batch mutation tool with no output schema and full schema coverage, the description covers scope, use case, and return value (progress summary). It could note throttling or the superadmin-only path, but those are documented in the schema, leaving only minor 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%, so all four parameters (force, limit, agentId, customerId) are fully documented in the schema itself. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema carries the burden.

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), resource (insights), and scope (all runs of an agent), which implicitly separates it from the single-run 'regenerate_run_insights' sibling. It is clear what the tool does, though it never names the sibling it contrasts with by name.

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 clear conditions for reaching for this tool. It stops short of naming alternatives (regenerate_run_insights, refresh_agent_insights) or stating when NOT to use it, so it is good but not complete routing 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 only declare readOnlyHint=false and destructiveHint=false; the description adds meaningful behavior beyond that: asynchronous execution with an immediate jobId return, repeated runs per scenario, and median-based aggregation. It does not mention permission requirements or expected runtime, which leaves a modest gap for a job-creating tool.

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 core action front-loaded, then the mechanics, then the follow-up call the agent needs. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description helpfully states the immediate return value (jobId) and the polling tool, which is the key thing an agent must know for a long-running job. It stops short of covering failure modes or estimated duration, so it is strong but 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 every parameter including baseline vs. challenger ordering, goal enum, and per-scenario run counts. The description restates the baseline/challenger concept and the 3-runs/median default, adding only marginal value beyond the structured field.

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 — comparing multiple LLM models on the same agent scenarios — and clarifies the baseline-then-challenger structure, which distinguishes it from siblings like start_model_test or simulate_ab_test. An agent can tell what it produces (per-scenario deltas) 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?

Gives clear operational context: it runs a job and returns a jobId immediately, so the agent must poll with get_benchmark_status. It does not, however, say when to prefer this over adjacent siblings like start_model_test, regression_test, or simulate_ab_test, so the selection guidance is incomplete.

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), the description discloses the permanence of the binding, its idempotency on repeat calls, the refusal mode for a conflicting version, and the reassurance that it freezes nothing, trains nothing, and spends nothing. That is substantive behavioral context annotations alone could not 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?

Three tight sentences plus a scope tag; the permanence and no-op/refusal rules are front-loaded, and every clause earns its place 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 and only partial annotation coverage, the description fills the gaps an agent needs: the write scope, the permanence semantics, the idempotency and refusal outcomes. Nothing required to call this 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%, so the schema already documents projectId, datasetId, versionId, and the superadmin-only customerId. The description only adds provenance for versionId (list_dataset_versions); it adds no syntax or format 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 (bind) and resource (the one frozen dataset version a fine-tuning project trains on), and explicitly contrasts with freezing/training/spending so the agent knows what this does not do. It is easily distinguished from freeze_dataset_version and list_dataset_versions.

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 source of the input (list_dataset_versions), states the permanence rule, and gives explicit when-not behavior: re-binding the same version is a no-op, a different version is refused, and a new project is required to train on another version. This is exactly the routing and exclusion guidance an agent needs.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, but the description reassures the agent this is “diagnosis only,” which reads as a safe, non-mutating operation. The reassuring “diagnosis only” framing directly conflicts with the destructive annotation, and the description never discloses what state the tool actually mutates. This is a misleading safety signal.

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 purpose and followed by return contents and scope. Every sentence carries information; minor room to tighten the return-value enumeration.

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 appropriately summarizes the return shape (classification, next strategy, per-metric breakdown). The only meaningful gap is the failure to acknowledge the destructive/state-changing behavior declared by the annotations.

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 (processId, customerId) are already documented in the schema. The description adds no parameter-level 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?

States a specific verb and resource (“Diagnose why an optimization failed to produce a winner”) and enumerates the concrete outputs (failure classification, next strategy, per-metric breakdown). An agent can distinguish it from the action siblings (trigger_optimization, stop_optimization, fix_worst_run) 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?

Provides clear context for when to use it (after a failed optimization with no winner) and explicitly bounds the scope with “Does NOT trigger a restart — diagnosis only.” It does not name a specific alternative tool, so it stops short of full routing 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 only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that by explaining that a closed project 'records nothing further' (terminal, effectively irreversible) and that a diagnosed rerun opens a new project referencing rerunOfProjectId. It does not, however, cover permission requirements or error 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 clauses, front-loaded with the action, followed by the terminal-state consequence and a scope tag. Nothing is padded, though the trailing 'Scope: write.' largely restates the 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?

For a 3-parameter mutation with no output schema, the description covers terminality and the follow-on rerun semantics, which is the information an agent most needs. It stops short of idempotency, permissions, and failure behavior.

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 67%, with projectId and customerId already documented in-schema. The description says the close carries a 'reason' but does not explain the enum meanings (candidate_approved, gate_failed, abandoned, superseded), which is the one place it could have compensated. Baseline 3 for mid coverage.

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 (close a fine-tuning project) and immediately names the required input (its reason), which separates it cleanly from create_fine_tuning_project, get_fine_tuning_project, and list_fine_tuning_projects. An agent can identify the operation 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?

The description implies when this is used (terminal outcomes such as an approved candidate or a failed gate) and notes the rerun path, but it never states when to prefer close_fine_tuning_project over alternatives or what preconditions must hold. Usage is inferable from the reason enum 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?

Annotations only tell the agent this is a non-read-only, non-destructive write. The description adds substantive behavior beyond that: model-dependent parameter compatibility (Opus 5 uses reasoningEffort and rejects temperature/topP) and the post-creation prerequisite of create_run. It omits whether creation is reversible or what the response contains.

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?

Purpose is front-loaded in the first clause, followed by the high-value model caveat and the workflow note. The capitalized IMPORTANT/NOTE markers are slightly heavy-handed, but each sentence carries real information with no 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 16-parameter creation tool with no output schema, the description covers the two things an agent most needs: the required model choice and the follow-up create_run step. It does not say what the creation returns (e.g. an agent id needed downstream), which is the main residual 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 100%, so every parameter including llmModel, temperature, topP and reasoningEffort is already documented inline. The description reinforces the model-to-parameter interaction, but that information is duplicated from the schema rather than adding new semantics, 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 ('Create a new agent for optimization'), making it distinguishable from update_agent, delete_agent, list_agents and the adjacent create_run/create_persona siblings. It does not explicitly name an alternative, but the purpose is 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?

Gives clear procedural guidance: specify the LLM model, ask the user which model when unspecified, and upload run transcripts with create_run before running optimization. That is real when-to-use sequencing, though it never contrasts with update_agent for modifying an existing 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 only declare readOnlyHint=false and destructiveHint=false. The description adds genuinely useful traits beyond that: the clustering is deterministic, candidates are verified on their own checks, and the operation incurs no training cost. It omits auth/permission requirements (e.g., the superadmin constraint implied by customerId) and output/return 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?

Front-loaded with the verb+resource, then supporting clauses; the closing 'Trains nothing and spends nothing' earns its place as a cost/safety signal. Dense but not padded, though the middle clause listing is slightly heavy.

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 mutation tool with no output schema, the description conveys what it does and key behavioral traits (deterministic, cost-free, verification-based). Missing only return-value expectations and the permission nuances around customerId, which are minor given the annotation coverage.

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 four parameters (name, agentId, customerId, splitConditionKeys) including defaults and limits. The description adds no parameter-level detail, 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 ('Curate a dataset from an agent's completed runs') and details the internal process (extracts candidates, clusters by type × instruction version × conditions, admits verified successes). This clearly separates it from read/version siblings like get_dataset, list_datasets, and freeze_dataset_version.

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 establishes clear context ('completed runs') and disambiguates scope by declaring 'Trains nothing and spends nothing,' steering the agent away from fine-tuning/optimization siblings. It stops short of naming explicit alternatives or when-not conditions, so it doesn't reach the 5 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 only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond by stating the non-effects (no training, no spend, no version binding) and the auth requirement (approve scope or a human) for the follow-up steps. This is exactly the behavioral context a mutation tool needs.

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 operation and its scope, then the constraints. Dense but every clause earns its place; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-param nested-object tool with no output schema, the description covers purpose, non-effects, and scope requirements well. It does not describe the response (e.g., the created project id) but with no output schema that 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 coverage is 83%, so the schema already documents most parameters (name, agentId, datasetId, objective, customerId, rerunOfProjectId). The description restates the core shape ('one agent, one objective, optionally the dataset') but adds no syntax or format 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: one agent, one objective, optionally the dataset') and immediately distinguishes the scope of the operation. An agent can tell it apart from freeze_dataset_version and decide_approval, which are 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?

Explicitly says when to use it and what it does NOT do ('trains nothing, binds no version and spends nothing'), then names the sibling tools (freeze_dataset_version, decide_approval) that handle those downstream decisions. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation-but-safe profile is covered structurally. The description adds nothing beyond that: no note on name uniqueness, validation, required permissions, or side effects on simulation runs.

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 tight, though arguably too terse given the tool's creation semantics.

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 3-parameter create tool with full schema coverage and annotations covering the safety profile, the essentials are present. It stops short of describing what a created persona enables or how it relates to simulations, leaving a modest 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 each of the three parameters (name, tags, description) documented including examples. The description adds no further parameter meaning, 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 ('Create') and resource ('persona') and adds the domain purpose ('for simulation testing'), which orients the agent. However, it does not differentiate from siblings like update_persona or create_agent beyond the obvious verb 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?

The phrase 'for simulation testing' hints at context, but there is no explicit guidance on when to create a persona versus using an existing one, whether duplicates are allowed, or what the prerequisites are. Usage must be inferred.

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 mark this as a write (readOnlyHint=false) but say nothing about side effects; the description adds that auto-creating a prompt also activates it automatically before the run is logged, which is real behavioral context. It also warns that tool calls are not auto-captured and must be sent explicitly. No info on permissions beyond the schema's superadmin note.

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 core action, then uses short labeled sections (REQUIRED FOR OPTIMIZATION, IMPORTANT, numbered options, TOOL USAGE) to make it scannable. It runs long for a description, but every block carries distinct operational information rather than restating 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 12-parameter mutation tool with no output schema, the description covers the critical workflows, the optimization prerequisite, the content constraint, and the auto-create side effect. It omits what the created run returns (e.g. run ID), which would help chaining into trigger_optimization.

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 already 100%, so the baseline is 3, but the description adds the conditional grouping rule (prompt + promptName + llmModel must be supplied together for auto-create) and explains the purpose of toolDefinitions vs toolCalls (tools available vs calls actually made). That is meaning beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Create a new run record from a real user/AI dialogue transcript.' The distinction from siblings is implicit but clear (list_runs/get_run/delete_run/sync_runs are different operations), and the description immediately qualifies the required input shape.

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 ties the tool to its dependent workflow ('you must upload runs before running trigger_optimization'), and lays out two mutually exclusive usage paths (existing promptId vs auto-create with prompt + promptName + llmModel). It also states a hard when-not rule for content: no system prompts, instructions, or configuration text.

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 disclose readOnlyHint=false and destructiveHint=false, so the mutating-but-non-destructive profile is known. The description adds nothing beyond that: no auth requirements, no idempotency or duplicate-URL behavior, and no note that the endpoint becomes active immediately.

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, exactly the right size for a simple create tool. It is efficient, though it forgoes the opportunity to add any routing or prerequisite 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 4-parameter tool with full schema coverage and no output schema, the basics are covered by the schema, so the description need not explain return values. However, it leaves out behavioral details an agent would want, such as whether webhook secrets are issued or how to verify deliveries.

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 url, events, customerId, and description all documented in the schema including the full event list and the superadmin scoping of customerId. The description adds no syntax or semantic 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 (Create) and resource (webhook endpoint) plus the intent (receiving event notifications). An agent can distinguish it from delete_webhook, get_webhook, and update_webhook, though it does not name those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of alternatives, and no prerequisites such as required permissions or notes about the superadmin customerId path. The 'receiving event notifications' clause implies context but does not instruct the agent when this tool 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?

With annotations only covering safety/idempotency hints, the description discloses substantial extra behavior: decisions are final and non-rewritable (consistent with idempotentHint=false), the approval executes nothing itself, and the decision is stamped with the calling key's id and scope. This is exactly the audit and side-effect context an agent cannot infer from 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?

Front-loaded with the core action, then finality, side effects, and scope in tight, information-dense sentences. Every sentence carries distinct meaning with no filler or repetition of 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 mutation tool with no output schema, the description covers the essential unknowns: finality/irreversibility, that it triggers no execution itself, and the exact permission scope required. Nothing an agent needs 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 already 80%, covering note, projectId, approvalId, and customerId; the description only loosely maps 'training spend or the production switch' onto the state enum. It adds little parameter meaning 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?

States a specific verb pair (approve/decline) and a precise resource (a requested fine-tuning approval, either training spend or the production switch). An agent can distinguish this decision action from the surrounding request/list/record siblings 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?

Gives a concrete precondition ('an already-decided approval is refused') and a hard scope gate ('write, admin and superadmin keys cannot call it'), so the agent knows when it is eligible to call. It does not name an explicit alternative (e.g., request_approval) for creating rather than deciding, which keeps it 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, but the description adds context those flags cannot carry: exactly which dependent data is destroyed, that the operation is permanent/irreversible, and that it is scoped to the authenticated customer. That is real added value over the structured signals.

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 waste, and the critical blast-radius information is front-loaded. The irreversibility warning lands before the scoping note, which is the right ordering for a destructive 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?

For a destructive, no-output-schema tool with full schema coverage, the description covers the essentials: scope of destruction, irreversibility, and tenant boundary. Auth/permission requirements beyond the superadmin note in the schema are not spelled out, which is the only notable 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% and all three parameters are documented in the schema, including the confirm safety flag and the superadmin-only customerId. The description's scope sentence loosely touches customerId, but adds no syntax or format 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 (delete) and resource (agent) and enumerates the exact cascade: runs, run insights, prompt insights, prompt metrics. This distinguishes it from the other delete_* siblings (delete_run, delete_user, delete_webhook, delete_optimization) without the agent needing to open their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the enumerated cascade tells an agent this is the broad option, so an agent wanting to remove only runs should reach for delete_run instead. However, no alternative is named, and there is no statement of prerequisites or when-not-to-use beyond the irreversibility warning.

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 known; the description adds real value by naming the cascading deletions and stating irreversibility explicitly. It stops short of noting that the confirm flag must be true or that customerId is superadmin-only, both of which live 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?

Two tight sentences, with the core action and cascade scope front-loaded before the destructiveness warning. No filler or repetition.

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 full annotation coverage, complete schema descriptions, and no output schema, the description supplies everything needed to call it safely: scope, cascade, and irreversibility. The only gap is the missing routing hint versus stop_optimization.

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 fully documented in the schema. The description adds no syntax, format, or behavioral detail about the parameters themselves, 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 uses a specific verb (delete) plus resource (optimization process) and enumerates exactly what is removed: activities, runs, candidates, feedback. The scoping statement ('authenticated customer') distinguishes it from any superadmin path and from non-destructive siblings like stop_optimization.

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 establishes context (permanent, irreversible deletion) but never says when to choose this over the sibling stop_optimization, nor when deletion is inappropriate. The destructive framing implies care, yet no explicit alternatives or preconditions are named.

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 real context beyond them: the deletion is permanent/irreversible and it cascades to the run's insights, and the operation is confined to the authenticated customer's scope. It does not mention the required confirm flag (left to the schema) or any auth/rate-limit nuance, so it is strong rather than exhaustive.

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 terse sentences, front-loaded with the destructive action and its cascade, then the irreversibility warning, then the scope constraint. Nothing is padded and the most important fact (permanent, irreversible) appears immediately.

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 destructive tool with no output schema and annotations that already flag destructiveness, the description covers the essentials an agent needs: permanence, cascade to insights, and customer scoping. Only a note about the confirm prerequisite or irrecoverability mechanics would fully round it out.

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 conversationId, customerId, and confirm are all documented in the schema; the description adds no syntax or format detail for any of them. Baseline 3 applies when the schema carries the parameter burden, which is the case here.

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 ('Permanently delete a run') and even names the cascading side effect ('and its insights'), which cleanly separates it from the other delete_* siblings that target agents, optimizations, users, and webhooks. It stops short of explicitly contrasting with any sibling or an alternative action, so it lands just below the top mark.

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 alternatives (e.g. archive, or how it differs from other removal tools). The scope note 'Scoped to the authenticated customer' describes reach rather than when to invoke the tool, leaving usage entirely 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 cover destructiveHint=true and non-idempotency, but the description adds material context beyond them: permanence/irreversibility and the last-admin guardrail. It stops short of stating what a successful or refused response looks like.

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 action and scope, then the destructive warning, then the guardrail. Every sentence earns its place 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?

For a destructive mutation with no output schema and fully documented params, the description covers scope, irreversibility, and the refusal rule. It could be stronger by noting the confirm=true prerequisite, though the schema already enforces that.

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 (userId, confirm, customerId) are already documented in the schema, including the superadmin-only customerId. The description adds only the customer-scoping constraint, 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?

Specific verb (delete) plus resource (user account) with explicit scope ('within the current customer'). Clearly separable from the many other delete_* siblings (delete_agent, delete_run, delete_webhook, delete_optimization).

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 decisive when-not condition: it refuses to delete the last remaining admin in a customer, which tells the agent the call can fail on a business rule rather than a schema error. It doesn't name alternatives, but for a terminal delete there is no real substitute to route to.

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=true, so the safety profile is covered structurally. The description adds nothing beyond that: no statement of irreversibility, no permission requirements for the superadmin-only customerId path, no note on side effects such as invalidating deliveries.

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 short sentence is front-loaded and waste-free, but at this length it reads as under-specification rather than disciplined brevity. There is no room for structure to evaluate.

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 the description omits the one thing an agent cannot infer from structured fields: that deletion is permanent and what it cascades to. Annotations and a complete schema carry the mechanical details, but the description leaves the operation's consequences 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 both webhookId and the superadmin-only customerId are fully documented in the schema itself. The description adds no syntax or format detail, 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?

"Delete a webhook endpoint" is a bare restatement of the tool name delete_webhook; it names a verb and resource but adds no scope, target system, or distinguishing detail. It is effectively a tautology, though it is not misleading.

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 alternatives named (e.g., update_webhook vs delete_webhook), and no conditions or prerequisites described. An agent gets zero routing help from the description text.

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 flag destructiveHint=true and readOnlyHint=false, and the description usefully adds what actually happens: status becomes dismissed and the reason is persisted as feedback for Converra learning. It doesn't state reversibility or permission requirements beyond what the schema notes for 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?

Three sentences, front-loaded with the action and effect, with example utterances at the end. The feedback idea is briefly repeated between the first and second sentences, a minor redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with full annotation coverage, no output schema, and three well-documented parameters, the description covers action, effect, and fit. It leaves out reversibility and any post-dismissal behavior, which keeps it from being fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining that the reason parameter is stored as feedback used for future optimizations, giving it downstream meaning the schema text only hints at.

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) and resource (pending deployment/PR) plus the resulting state change to 'dismissed'. It is clearly a rejection action, but it does not explicitly distinguish itself from nearby siblings such as decide_approval or request_approval that also touch the approval flow.

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 trigger phrasings ('reject this PR', 'dismiss this deployment', 'I don't want this change') that map user intent to this tool. It gives no explicit when-not-to-use or named alternative, so it stops short of full routing 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 only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that — it mutates the owning agent by attaching a regression scenario, and it will refuse certain failure categories outright. It stops short of covering idempotency (what if the scenario already exists) or whether the optimization launch needs approval.

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: the action first, the workflow routing second, the guardrail third. No filler, and the most decision-relevant information is front-loaded.

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, the description covers the side effect (scenario added to the owning agent), the optional chained action, and the refusal path. It could say more about what the caller receives back or how to follow up on the launched optimization, but nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds genuine meaning by tying 'optionally launch an optimization targeting that failure' to the autoLaunch parameter, clarifying its downstream effect rather than just restating it.

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 compound action: convert a failed run into a regression scenario on its owning agent, with an optional optimization launch. It is clearly distinguishable from add_regression_scenarios (manual scenario creation) and trigger_optimization (standalone optimization), since it scopes the action to a diagnosed failure.

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 entry-point sibling (get_worst_run) and the workflow (pipe get_worst_run → fix_worst_run), plus an explicit exclusion: runs whose failure is not prompt-fixable (tool_config, model_limitation). 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?

Goes well beyond the annotations: irreversible action, 409 abort on a violated check, diversity-floor behavior (freezes but marked blocked), and scope enforcement that write/admin/superadmin keys cannot call it. It also discloses what the response contains (counts, coverage, hashes, never examples) and how the version is stamped.

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 each subsequent sentence carries distinct value (irreversibility, error behavior, response shape, scope). The em-dash phrasing is dense, but nothing 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?

Despite no output schema, the description covers return contents, failure semantics, authorization scope, and irreversibility — everything an agent needs to invoke it correctly and interpret the result.

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 (datasetId references list_datasets; customerId notes superadmin-only). The description adds no parameter-level detail, so the schema carries the load and 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 under the leakage contract), immediately distinguishing it from siblings like create_dataset, bind_dataset_version and list_dataset_versions. An agent can tell exactly what this produces 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?

Clearly frames when it applies — freezing the version that training binds to under the leakage contract — and states the required approve scope. It does not explicitly contrast with the closest sibling (bind_dataset_version), so routing between the two still requires inference.

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

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

The annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false), lowering the disclosure burden. The description adds useful scope by naming the returned content, but says nothing about the superadmin impersonation semantics implied by the customerId parameter or any auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the verb-resource-content order is efficient. It is appropriately sized, though there is no structural separation of scope from caveats.

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 read tool with a fully documented parameter and annotations covering safety, the description is nearly complete: the agent knows what it fetches and what it returns. The absence of any note about the superadmin-only impersonation path 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 coverage is 100% with a single optional parameter, so the schema already carries the full parameter burden. The description adds no additional semantics beyond it, which is 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?

States a specific verb ('Get') and resource ('account') and enumerates the payload ('organization details and subscription plan'), so the agent knows what comes back. It does not, however, distinguish itself from nearby read siblings like get_settings or get_usage, which is why it stops short of 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?

There is no when-to-use, no when-not-to-use, and no named alternative. An agent deciding between get_account, get_settings, and get_usage gets no routing signal at all from 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 establish this as a safe read (readOnlyHint=true, destructiveHint=false), so the description's burden is lighter; it still adds useful content semantics by spelling out the three item categories the queue surfaces. It does not cover ordering, pagination behavior, or how empty queues are represented, which are the remaining behavioral gaps.

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?

Content is front-loaded and dense: the item categories come first, the sibling exclusion second. The trailing 'Answers:' sentence is mildly redundant with the opening list, but it earns its place by framing the retrieval 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, the description carries the return-value burden and does so by enumerating what the queue contains, which is the key information an agent needs. It stops short of describing result ordering or default truncation behavior, but the essentials 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% and all three parameters (limit, datasetId, customerId) are documented in the schema, including the superadmin restriction. The description adds no parameter-level meaning 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?

The description names the resource (dataset-curation adjudication queue) and enumerates its contents precisely: clusters with no decision in force, unverified training targets, and members unresolved on their own evidence checks. It explicitly contrasts itself with get_review_queue, so an agent can distinguish the two 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?

It names the most confusable sibling and the condition that separates them ('This is NOT get_review_queue, which is the optimization PR queue'), and frames the use case via the questions it answers ('what needs adjudicating?', 'how much review is left?'). That is explicit when-to-use plus when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered, but the description adds meaningful context beyond them by disclosing the shape of the response, including role-family fields (agentType, customer, instanceCount, siblings) and the multi-tenant SaaS scenario they surface. It stops short of 5 because it omits any note on permissions or size/cost of the fetch.

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, with the core purpose front-loaded, and the role-family explanation earns its length by clarifying the return payload. Slightly verbose on the SaaS framing, but no wasted filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only get with 100% schema coverage and no output schema, the description carries the return-value burden well by naming the fields an agent will receive. What remains thin is routing and permission context, which keeps it from a 5.

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 customerId are already documented in the schema, and the description adds no parameter-level detail or format hints. Baseline 3 is appropriate 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 specific verb and resource ('Get the full details of an agent') and enumerates what is returned (system prompt, configuration, metadata, role-family fields), which clearly separates it in granularity from list_agents and get_agent_status. It does not explicitly name a sibling it competes with, so it stops 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?

There is no when-to-use, when-not-to-use, or alternative-routing guidance. An agent must infer from 'full details' that this is the single-agent fetch versus get_agent_status or analyze_agent, and nothing clarifies when the customerId override is appropriate beyond the schema note.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so safety is already covered. The description adds that the response covers optimization state and performance metrics, but says nothing about caching, rate limits, or freshness of the status, and there is no output schema to fall back on.

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. It is efficient, though a single sentence this short leaves room for the routing and freshness detail that would make it stronger.

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 read-only two-parameter tool with full schema coverage and annotations, the description is minimally sufficient. It is missing sibling differentiation and any note on what 'status' contains beyond the two named facets, and with no output schema the agent can't confirm the return 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%, so both agentId and customerId are already documented. 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?

States a clear verb+resource ('Get the current status of an agent') and enumerates the payload ('optimization state and performance metrics'), which distinguishes it from siblings like get_agent (static config) and get_model_optimization_status (optimization-only). However, it doesn't explicitly name those siblings to sharpen 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?

No when-to-use, when-not-to-use, or alternative guidance. With ~100 sibling tools including get_agent, get_model_optimization_status, and get_fleet_overview, the agent gets no routing help for choosing this over an adjacent tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral value by disclosing that output changes shape over the lifecycle: activity-feed-style progress while running versus a full comparison with recommendation when complete. It stops short of covering rate limits or pagination.

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 tightly written sentences, front-loaded with the core action and then the lifecycle-dependent return shape. No filler or restated name/title 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 usefully characterizes both possible return states, which is the key unknown for a polling tool. Annotations cover the safety profile, leaving only minor gaps such as polling cadence and pagination.

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 (jobId, customerId, including the superadmin-only note) are fully documented in the schema. The description adds no parameter-level meaning beyond that, 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 (poll/get) and resource (benchmark job status and results), which is clearly distinct from the producer sibling benchmark_models and from other status pollers like get_simulation_status. It never names a sibling to disambiguate, 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?

The word 'Poll' implies repeated invocation after benchmark_models, and the jobId schema note ties it back to that tool, so usage is reasonably implied. There is no explicit when/when-not statement or named alternative to route the agent, so it stays at minimum viable.

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 this a safe read (readOnlyHint=true, destructiveHint=false), so the safety burden is lifted. The description adds useful content-level context about what is aggregated and that it surfaces a before/after example, but says nothing about scope of the aggregation window beyond the schema, permission requirements, or freshness/caching of the numbers.

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 aggregate payload front-loaded. The trailing example-question list is mildly redundant with the preceding enumeration but still earns its place as invocation cues.

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, zero-required-parameter tool with no output schema and full schema coverage, the description adequately conveys what the response contains. It is complete enough to call correctly; only the relationship to sibling impact/fleet tools is underspecified.

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%: days (lookback, default all-time, max 365) and customerId (superadmin only) are fully documented in the schema. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource — a cumulative impact summary across all deployments — and enumerates the payload (fixes shipped, issues resolved, failure reduction, before/after example). An agent can distinguish it from per-deployment siblings like get_deployment_impact, though it never names any alternative directly.

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 trigger questions ('how is Converra helping?', 'what was fixed?') imply when to reach for this tool, which is a real hint. However, there is no explicit when-not guidance and no routing between this and related read tools such as get_deployment_impact, get_fleet_intelligence, or get_fleet_overview.

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=true and destructive=false, so the safety profile is covered. The description adds real value beyond that: candidates are excluded from the response, and the non-obvious detail that reviewProgress spans every cluster while only the rows are paged. That pagination-versus-metric scope caveat is exactly the kind of behavioral context an agent cannot infer from structured fields.

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, zero waste, and correctly front-loaded: purpose first, then the exclusion/alternative routing, then the paging caveat. Each sentence carries distinct information an agent needs.

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 by enumerating what each cluster row contains and how members resolve. Combined with the paging caveat and sibling routing, the definition is nearly complete for a read tool, though it says nothing about result ordering or total-count signaling.

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 (limit, offset, datasetId, customerId, reviewState) is already documented in the schema. The description reinforces the paging/row concept and implies reviewState filtering but adds no format or syntax beyond what the schema provides. Baseline 3 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?

The description states a specific resource (one dataset) and precisely names what it returns: the cluster roll-up with review state, decision in force, and member resolution. It explicitly distinguishes itself from sibling tools by noting candidates are excluded and pointing to list_dataset_examples and get_review_case for the other 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?

It names the alternatives by name and the condition selecting each: list_dataset_examples for per-example admission and get_review_case for one cluster's evidence. This is explicit when-to-use/when-to-use-something-else routing, not a vague 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 establish readOnlyHint=true/destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses the default grouping (per-agent), the alternate grouping (PR), and the kinds of values returned (parity verdicts, model IDs, score definition, estimated cost delta). It omits pagination/cursor behavior and the superadmin-only nature of customerId, keeping it from 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?

Three tightly packed sentences: purpose and payload first, mode/default behavior second, intent-matching example questions third. No redundancy and nothing buried — every sentence contributes to selection or invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-param, no-output-schema read tool, the description does the heavy lifting of describing the returned content (verdicts, model IDs, score definition, cost delta), which compensates for the missing output schema. It leaves cursor/pagination and status-filter semantics entirely to the schema, so it is strong but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all eight parameters (including the view enum and its default). The description reinforces view semantics and default grouping but adds no new syntax, format, or constraint detail beyond what the schema states; 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 ('see whether deployed fixes or model swaps worked in production') with an explicit enumeration of what the response contains (parity verdicts, model IDs, score definition, cost delta). It also distinguishes its two modes — per-agent by default vs PR-grouped with view='pr' — so an agent can tell it apart from neighbors like get_pr_context or get_score_timeline.

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 usage context via the default grouping rule and the 'view=pr' alternative, plus three example questions ('did my fixes work?', 'what PR changed this?', 'show me PR impact') that map intent to invocation. It does not, however, name a competing sibling tool or state when NOT to use it, so it stops short of explicit alternative routing.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds materially useful behavior: that gate elements surface as names and outcomes only (a deliberate detail limitation), which is not derivable from the schema or annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The payload contents are front-loaded in one dense but well-formed sentence, followed by a short routing sentence for get_gate_result. Every clause carries information, though the opening enumeration is heavy.

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 appropriately carries the burden of describing returns by enumerating the five component groups. It is complete enough for an agent to call the tool and know what to expect, though it is silent on pagination or size characteristics.

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 (projectId, customerId), both already documented in the schema including the superadmin caveat. The description adds no syntax or format detail 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?

The description enumerates exactly what the resource contains — the eight-step journey, bound dataset version, review progress, training job facts, and approvals — so an agent can tell it apart from siblings like get_training_job or get_gate_result. The retrieval verb is only implied (carried by the name), so it stops short of a full verb+resource statement.

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 get_gate_result when only a single verdict element is needed, which is clear alternative guidance. It does not state broader when-to-use conditions (e.g., versus list_fine_tuning_projects or get_training_job), so it is clear context without full 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 and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context — that results are ranked by impact and that badges indicate Converra-deployed fixes — but says nothing about scoping, pagination, result volume, or freshness, which matter for a fleet-wide aggregation tool.

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 supported by concrete output details, then scenario questions. The example-question sentence is slightly padded but earns its place by mapping to real user phrasings; overall there is little waste.

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 readOnly annotations, a single optional parameter, and no output schema, the description is nearly self-sufficient — it explains what the returned data contains and how fixes are signalled. The remaining gap is sibling disambiguation against the other fleet/insight tools, which is not addressed.

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 there is only one optional parameter (customerId, superadmin-only), so the schema carries the parameter burden adequately. The description does not mention the customerId parameter or its superadmin restriction, but baseline 3 is appropriate when the schema is fully documented.

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 — fleet-level failure patterns with business impact descriptions and fix verification status — and enumerates the concrete content (before/after failure counts, 'Improved'/'Fixed' badges). It's clear what it returns, but 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 three example questions ('what are the biggest issues hurting my fleet?', etc.) give implied usage context and make the intended scenario fairly obvious. However, there is no explicit when-not guidance and no sibling is named as an alternative, so the routing decision against get_fleet_overview or get_insights 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered without the description's help. The description adds that results are aggregated fleet-wide and hinted at remediation ('what has Converra fixed?'), but says nothing about pagination, result size, or scope limits beyond 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?

Front-loaded with the resource and its payload fields, followed by a positioning sentence and illustrative questions. The question framing is somewhat promotional but does double as usage guidance, so waste is limited.

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 enumerating the return fields (scores, run counts, failure rates, deployment stats). For a zero-required-parameter read tool with full schema coverage, this is largely sufficient, though aggregation granularity and time window are 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%: sortBy is documented with enum meanings and default, and customerId's superadmin restriction is stated 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?

States a specific resource (fleet-level dashboard of all agents) and enumerates the content it exposes: performance scores, run counts, failure rates, deployment stats. It does not, however, explicitly distinguish itself from nearby siblings like get_fleet_intelligence or get_fleet_timeline, which also sound fleet-wide.

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?

Calls itself 'the entry point for understanding agent health across the fleet' and frames use cases as questions, giving an agent a clear sense of when to reach for it. It names no alternatives and states no when-not conditions, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral detail beyond that: the return contents (daily fleet-wide avg score, total 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 core purpose, then the usage cue, then the return payload. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by enumerating what is returned (avg score, run count, contributing agents, unioned deployment markers). Combined with a fully documented input schema, an agent has everything needed 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 description coverage is 100%, so both parameters (days with default 30/max 365, and customerId superadmin targeting) are fully documented in the schema. The description adds no parameter-specific detail, 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 (timeline retrieval), resource (run-weighted score timeline), and scope (aggregated across ALL agents in the fleet). This clearly separates it from per-agent timeline tools like get_score_timeline in the sibling list.

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 an explicit when-to-use framing ('how is the whole fleet trending over time?') and contrasts it with the per-agent alternative ('instead of one agent at a time'), which functionally identifies get_score_timeline. It does not name the sibling tool outright, so it stops short of a full 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds genuine context beyond that: the verdict is 'minted outside the app by the gate harness', so the data is externally produced and immutable, and dry-run results are explicitly labelled and are not acceptance evidence. That provenance and labelling detail materially affects how an agent should treat the returned values.

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 what is returned, then provenance, then the dry-run caveat. Slightly ornamental phrasing ('minted outside the app by the gate harness') but no filler or repetition.

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 the return shape; it gestures at 'element by element, with each element's own scalar measurements' but does not clarify what an element is or what fields a verdict carries. The dry-run labelling caveat is valuable, but an agent still lacks a clear picture of the response structure.

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 jobId, projectId, verdictId (including its default-to-protected-acceptance behavior) and the superadmin-only customerId are already documented in the schema. The description adds no parameter-level detail, which is acceptable given full coverage but earns no extra credit.

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: it reads 'one frozen-gate verdict, element by element, with each element's own scalar measurements'. It also implicitly separates itself from the write-side sibling record_gate_result by saying it 'only reads what was recorded'. However, it never names or contrasts with the other nearby read tools (get_verification_evidence, get_adjudication_queue, get_review_case), so the boundary is only partly drawn.

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. The only routing signal is the caveat that a development dry run is never acceptance evidence, which hints at how to interpret results rather than when to call the tool. Nothing tells the agent how this differs from record_gate_result or the other verdict/evidence readers.

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 behavior is covered. The description adds that the output is aggregated performance insights derived from run data, but does not disclose return structure, aggregation dimensions, or any other behavioral traits 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 no filler or redundancy. Every word contributes to the purpose statement, and nothing 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?

For a read-only aggregation tool with fully described parameters and annotation-covered safety, the definition is minimally adequate. However, without an output schema or additional description, an agent still lacks clarity on what specific performance insights are returned or how they are aggregated.

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 including agentId, days, and the superadmin-only customerId are already documented. The description does not add any parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Get'), resource ('aggregated performance insights'), and scope ('for an agent based on run data'). It distinguishes itself from run-level tools like get_run_insights by specifying agent-level aggregation, but it does not explicitly name or contrast with the closest 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?

Provides no when-to-use or when-not-to-use guidance and does not mention alternatives such as get_run_insights, refresh_agent_insights, or get_fleet_intelligence. Usage context is only implied by the phrase 'for an agent based on run data'.

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 that the result is code/packages/config rather than prose, which is useful since there is no output schema, but it discloses nothing about freshness, breadth, or limits of the guide.

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, purpose front-loaded, followed by the interaction instruction. Efficient, with only mild redundancy between the description's stack examples and the schema's identical examples.

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 generation tool with no output schema, the description tells the agent what it will receive (code, packages, config) and what to provide. Nothing essential to calling 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 all four parameters are already documented with examples. The description's stack examples duplicate rather than extend the schema's own examples, so it adds no semantics beyond what is structured.

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 (step-by-step integration guide) and concretely elaborates the output — 'exact code, packages, and configuration'. This clearly separates it from sibling tools like verify_integration or list_integrations, though it never names those alternatives.

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 second sentence implies usage: describe your stack and get matching code. That is clear context for when to reach for it, but there are no exclusions and no routing against verify_integration or list_integrations, which the agent must infer.

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 genuinely new context the annotations cannot: the response progresses (progress while running) and matures into a full report on completion, which matters when there is no output schema. It stops short of stating terminal/error states or polling cadence.

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 short sentences, no filler, and the core action (poll for status) is front-loaded. The second sentence earns its place by describing the two-stage return behavior.

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 must carry return-value meaning and it does so at a high level: progress during execution, full report after completion. It is nearly complete for a polling tool, though failure/terminal-state handling and expected call cadence remain 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%: jobId is documented as the value returned by optimize_model and customerId as a superadmin-only target. The description adds nothing about either parameter, so the baseline 3 is correct given the schema carries the full load.

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: poll a model optimization job for status and results. It is clear what the tool does, but it does not distinguish itself from near-siblings such as get_optimization_details, get_training_job, or get_simulation_status, which an agent might otherwise confuse with 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?

"Poll" implies repeated invocation until the job finishes, which is useful implied guidance. However, it names no alternatives and gives no explicit when-to-use/when-not-to-use conditions (e.g., versus get_optimization_details or get_training_job), 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds that the response contains variants, activities, and results, which is useful disclosure of scope, but it does not address the includeActivities toggle behavior or the superadmin-only customerId constraint (both left to 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 no filler; the verb and scope come first and every clause carries 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 read tool with no output schema, the description is adequate because it names the entity types returned (variants, activities, results), but it gives no sense of response shape, size, or pagination, and does not clarify the relationship to sibling retrieval tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (processId, customerId, includeActivities) are already documented in the schema. The description adds no format, default, or semantics 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?

States a specific verb (Get) and resource (optimization details) and enumerates what is included: variants, activities, results. It is clear on its own, but it does not explicitly differentiate itself from close siblings like get_variant_details, get_run, or list_optimizations, leaving the agent to infer which 'optimization' entity is meant.

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 alternatives despite a dense sibling list containing get_variant_details and list_optimizations. Usage is only implied by the required processId parameter.

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 useful content context by naming what is returned (description and usage stats), but says nothing about permissions beyond the schema note, nor about error behavior for an unknown ID.

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 no filler, and the core action is front-loaded. It is appropriately sized for a simple lookup tool, though it could carry one routing clause at no cost.

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 read tool with full schema coverage and annotations covering safety, the definition is nearly sufficient; naming the returned fields compensates for the absent output schema. The only real gap is routing guidance against list_personas.

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 personaId and the superadmin-only customerId are fully documented in the schema. The description adds no parameter detail beyond that, 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 ('Get') and resource ('a specific persona') plus the payload it returns (description and usage stats). It is clear what the tool does, but it never names its sibling list_personas, so the agent must infer that this is the single-item counterpart.

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: 'a specific persona' signals that a known personaId is required, which distinguishes it loosely from list_personas. There is no explicit when-to-use/when-not statement and no mention that list_personas should be used to discover IDs.

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 readOnlyHint=true and destructiveHint=false annotations already establish the safety profile. The description adds useful behavioral context by saying it returns a comprehensive set of review evidence in one call and lists the categories of information included. It does not contradict annotations and adds meaningful value beyond them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then supports it with a return-content list and example questions. The long enumeration of returned items is justified by the absence of an output schema, though it is somewhat list-heavy rather than maximally 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?

For a read-only getter with no output schema, the description does a good job of explaining the rich content returned and the review scenarios it supports. It does not cover pagination, limits, or relationships to alternative tools, leaving a few minor 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%, so the schema already documents deploymentId, customerId, and includeDiff with clear descriptions. The tool description adds no parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate 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?

The description clearly states it provides a comprehensive reviewer briefing for a specific deployment/PR and enumerates the content returned. It does not explicitly name or differentiate itself from similar siblings such as get_review_case or get_verification_evidence, so it is clear but not sibling-differentiating.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides concrete usage signals via example user intents: 'tell me about this PR', 'should I merge this?', 'what does this fix?'. It establishes when to reach for this tool, but gives no explicit when-not-to-use guidance or alternative tool recommendations.

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 the useful detail of what the read returns (arm counts, decision state), but says nothing about the superadmin-only customerId escalation path, pagination, or freshness of the status. Modest value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler. Every clause (status, arm counts, decision state) earns its place by telling the agent what comes back.

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 returned fields, and annotations cover the safety profile. It is nearly complete for a simple read; only the elevated-permission path and any staleness/pagination behavior are unaddressed.

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 schema itself documents both productionTestId and the Converra-superadmin-only customerId. The description adds no parameter semantics of its own, 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 (Get) and a specific resource (production A/B test), and enumerates what it surfaces: status, arm counts, decision state. It is clearly distinguishable from mutation siblings like start_production_test or promote_production_test, but it does not differentiate itself from read siblings such as get_variant_details or get_gate_result.

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 and no alternatives named. An agent must infer that this is the status-read for a production test rather than a simulated or benchmark test (simulate_ab_test, start_model_test, get_benchmark_status all exist as siblings). No prerequisites or exclusions 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context by disclosing the returned contents, including source tracking (synthetic vs production reproduction) and baseline scores, which an agent would not otherwise know. It omits any permission/rate-limit detail, but the annotation baseline is already satisfied.

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 resource and payload front-loaded, and the interpretive purpose second. Nothing is wasted or redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with no output schema, the description usefully enumerates the returned fields, which compensates for the absent output schema. It is nearly complete; only the inability to reference alternatives for this specific use-case 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% and both parameters (agentId, customerId) are already documented in the schema, including the superadmin-only note. The description adds no syntax, format, or default 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?

The description pairs a specific verb ('Get') with a precise resource ('the regression test suite for an agent') and enumerates the payload (scenario details, source tracking, baseline scores). It is clearly distinct from write-oriented siblings like add_regression_scenarios and regression_test, though it does not name them 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 offers a purpose-level context ('Use this to understand what scenarios guard against regressions during optimization'), which implies the usage. However, it gives no when-not guidance and does not name alternatives (e.g., add_regression_scenarios for writing, regression_test for executing), so the routing guidance is only implied.

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 (readOnlyHint=true, destructiveHint=false), so the description's real contribution is paging behavior: it explains that members are paged because a cluster can hold hundreds, and that the contrasting verified success appears only 'when one exists'. That is genuine behavioral context beyond the annotations, though it says nothing about ordering, permissions, or error modes.

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, both load-bearing. The return contents lead, and the paging rationale is placed last as the consequence rather than mixed into the enumeration. 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?

No output schema exists, so the description carries the full burden of describing the return shape, and it does so thoroughly for a read-only detail endpoint — enumerating each section of the case. Minor gaps remain (ordering of decision history, whether members are sorted) but nothing an agent needs 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 coverage is 100%, so every parameter (clusterId, customerId, memberLimit, including the superadmin-only constraint and the default/max on memberLimit) is documented in the schema itself. The description only indirectly motivates memberLimit via the paging sentence, adding no syntax or format detail beyond what the schema already provides — baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource precisely — a single cluster's review case — and enumerates the contents (representative candidate, finding, evidence, proposed training target, verification, contrasting success, decision history, member page). An agent knows it retrieves the detail view for one cluster. It never states a verb or contrasts itself against near-siblings like get_review_queue or get_adjudication_queue, so differentiation is left to inference.

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: 'One cluster's review case' signals this is the per-cluster drill-down reached from a queue, and the schema notes clusterId comes from get_adjudication_queue or get_dataset. There is no explicit when-to-use, no exclusion, and no named alternative, so the routing decision is left for the agent to reconstruct from siblings.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the ordering/prioritization logic (issue severity, simulation evidence strength, wait time, agent run volume) and that the most impactful items come first. It does not mention pagination or default/max limits in prose, but the schema's limit param covers that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core definition before ranking detail and intent examples. No filler, though the quoted-questions sentence partially restates usage already implied by the first sentence, keeping it just shy of maximally 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?

For a read-only, zero-required-param listing tool with annotations covering the safety profile and no output schema, the description supplies what an agent needs: content, ordering rationale, and intent mapping. The only minor gap is not clarifying how it differs from the adjacent queue/approval tools, which the sibling list makes relevant.

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 params (limit, agentId, customerId) are already documented, including the superadmin-only note on customerId. The description adds no parameter-specific meaning beyond the schema, which is the correct baseline-3 outcome 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?

The description states a concrete verb+resource: a prioritized list of pending optimization PRs/deployments needing human review, and it specifies scope (human review, optimization artifacts). It stops short of differentiating from closely related siblings like get_adjudication_queue, list_pending_approvals, or get_review_case, so the agent must infer the boundary. Clear but not fully disambiguated.

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 gives clear usage context by enumerating the user intents it serves ('what should I review?', 'any pending PRs?', 'what needs my attention?'). This frames when to reach for it, but it names no exclusions or alternative tools for the many adjacent queue/approval siblings, leaving the when-not boundary unstated.

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 only the includeInsights default behavior, which is already in the schema, and says nothing about pagination, size limits, or what happens when the lookup key resolves to nothing.

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, front-loaded with the core action and immediately followed by the lookup mechanism. No filler or repetition.

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 tool with a fully documented schema, this is nearly sufficient: it covers the action, scope, and both lookup keys. It is mildly thin on what 'details' and 'insights' actually return, though the absence of an output schema makes that only 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 the baseline is 3. The description echoes the dual lookup-key semantics (run ID vs session ID) but adds no precedence rules or format/example beyond what the schema already states, and it ignores customerId and includeInsights entirely.

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 (run) with an explicit scope qualifier ('full details ... including insights') and two documented lookup keys. It is distinguishable from list_runs and get_run_insights, though it never names those siblings to make the boundary 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?

It explains the two ways to look up a run (Converra run ID vs external session ID), which is useful usage context, but gives no when-to-use guidance relative to the many sibling read tools (get_run_insights, get_run_finding_context, get_worst_run, list_runs). Usage is implied 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond the annotations: it returns exact publication and question hashes, and those hashes are specifically what is needed to record an answer, establishing the read-then-record relationship.

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 zero waste. The primary action is front-loaded, and the second sentence carries only the workflow-relevant detail about return values. Nothing is padded.

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 must convey returns, and it does specify publication and question hashes. Combined with full param coverage and read-only annotations, an agent has what it needs to call the tool, though a brief hint about sequencing with the recording tool would fully close the loop.

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 in the schema, including the superadmin restriction on customerId. The description adds only the framing 'for a run,' which maps loosely to conversationId and adds little beyond the schema. Baseline 3 applies 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?

The description states a specific verb and resource: fetching 'the next canonical evidence-bound calibration question for a run.' This distinguishes it implicitly from the write counterpart record_run_calibration_review, though no sibling is named. Purpose is clear without needing to open 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 implied rather than stated: 'the next ... question' and the note about hashes 'required to record the answer' signal this is a read step preceding record_run_calibration_review. However, there is no explicit when/when-not guidance or named alternative, leaving the agent to infer the workflow.

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 adds one useful behavioral trait — that the context is "bounded" (i.e., truncated/limited) — but never says how it is bounded, nor what happens when a finding has no transcript or insight available.

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 sentence, front-loaded with the verb and the key scope qualifier "bounded", followed by a compact enumeration of contents. The list is long but each item conveys real payload information, 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 usefully enumerates what the agent receives, and read-only annotations cover the safety profile. What is missing is the bound size/truncation rule and any indication of failure modes when context is unavailable.

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 (customerId, conversationId, responderRunId) are documented in the schema itself, including the responderRunId selection behavior. The description adds no parameter-level meaning 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 (run finding context) and enumerates the five content pieces returned, which lets an agent distinguish it from neighbors like get_run_insights or get_run_step_diagnosis. It stops short of explicitly naming which sibling it displaces for a given need.

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?

"for reviewing a run finding" implies the trigger condition, but there is no explicit when-not guidance and no named alternative among the many sibling readers of run data. Usage is inferable 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?

Annotations already establish this as a pure read (readOnlyHint=true, destructiveHint=false), so the safety profile is covered. The description does add genuine context beyond annotations by disclosing that the payload carries a terminal status and the activePublication CAS target needed for an external generation write, tying it to publish_external_run_insight_generation. It still says nothing about pagination, cost, or result size.

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 tight sentence with the resource and the full content list front-loaded; no filler. The trailing "activePublication CAS target required for an external generation write" is dense internal jargon, which slightly reduces first-pass readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with 3 fully documented parameters and no output schema, the description covers what comes back and why one field matters downstream. The remaining gap is selection guidance against neighboring insight/get tools, none of which the description addresses.

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 are already documented in the schema, making the 3 baseline appropriate. The description adds no format or syntax detail for sessionId, customerId, or conversationId, though it does clarify that these resolve to "a specific run."

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+resource ("Get detailed insights for a specific run") and enumerates what those insights contain (metrics, findings, terminal status, CAS target), which separates it from get_run, get_insights, and get_run_finding_context. It stops short of explicitly naming a sibling it is not, so it lands at 4 rather than 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?

There is no statement of when to choose this tool over get_run, get_insights, get_run_finding_context, or regenerate_run_insights, and no prerequisites or exclusions are given. The only routing hint ("sessionId used only when conversationId is not provided") 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 safety is covered. The description adds genuine behavioral context beyond that: the tool degrades gracefully by using trace data when available and falling back to transcript-based diagnosis otherwise, which tells the agent what it can expect from different runs.

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: the core capability and its outputs come first, followed by availability and data-source behavior. No filler or repetition.

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 well by naming the four diagnostic components. It is nearly complete, though it omits return format or pagination/size expectations, 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 both parameters (customerId, conversationId) are already documented in the schema. The description adds nothing parameter-specific, 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 step-level failure diagnosis for a run') and enumerates the concrete outputs: first failing step, cascade effects, root cause hypothesis, per-turn timeline. This is clearly distinguishable from general run tools like get_run, though it never explicitly names a sibling such as get_step_failure_aggregation to sharpen the 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?

The description states availability ('Available for all runs') and the data source fallback, which implies the tool is always applicable, but it gives no explicit when-to-use versus alternatives or when the aggregation sibling is preferred. Usage is implied rather than directed.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the output carries deployment markers marking PR merge points, which tells the agent the timeline interleaves score data with deploy events. It omits pagination/return-shape details, but for a safe read tool this is solid.

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 covering what it returns, followed by three brief exemplar queries. Nothing is padded, though the three example questions are somewhat redundant with each other and could be trimmed to two.

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 must characterize the return value, and it does: daily granularity plus deployment markers. Combined with a fully-documented 3-parameter schema and read-only annotations, an agent has enough to call it correctly; only the exact response shape stays 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 defaults and maxima (days default 30, max 365) and a superadmin-only note on customerId already documented. The description only restates the date-range and agent scoping, adding no format or edge-case semantics. Baseline 3 applies 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 specific verb+resource ('Daily score timeline for an agent over a date range') plus a distinguishing detail: deployment markers tied to PR merges. This separates it from get_fleet_timeline (fleet scope) and get_deployment_impact by implication, but it never names or contrasts with those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Three quoted example questions ('did overall performance improve after our fixes?', 'show me the score trend', 'what happened to scores this week?') give concrete scenarios for selecting this tool. There is no explicit when-not guidance or named alternative (e.g., use get_fleet_timeline for cross-agent views), which keeps it below 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 and destructiveHint=false, so the safety profile is covered. The description adds only the content scope of the read; it does not mention the superadmin/act-on-behalf semantics that the customerId parameter implies, nor any return shape or pagination.

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. It is appropriately sized, though it stops short of using its remaining room to distinguish itself from get_account.

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 annotations covering safety and a fully described schema, this is nearly complete; the description gives a rough picture of what settings are returned. The missing piece is disambiguation from get_account and update_settings.

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 customerId parameter is fully documented in the schema as '(Converra superadmin only) Target customer ID to act on behalf of'. The description adds nothing about parameters, which is the expected baseline when the schema does 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?

States a specific verb ('Get') and resource ('account settings') and enumerates the content categories returned (general preferences, optimization configuration). It is not, however, differentiated from the sibling get_account, so an agent must guess which of the two to call.

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 exclusions, and no mention of the obvious alternatives in the sibling list (get_account for account data, update_settings for modification). The agent gets no routing help.

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 that this is an async polling operation returning 'status and results,' but says nothing about polling cadence, terminal states, or whether partial results are returned mid-run.

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 waste. The core purpose is front-loaded and the routing hint to the producing tools follows immediately.

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 mention that results accompany status, but it does not enumerate possible status values or terminal states an agent would need to interpret a poll response. Adequate for a simple two-parameter read tool, with a minor interpretive 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%, including the origin of jobId and the superadmin-only nature of customerId, so the schema does the heavy lifting. The description adds no format or syntax detail beyond what the schema already states; 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 (status and results of an async simulation job), and explicitly ties itself to the two producing tools simulate_agent and simulate_ab_test, distinguishing it from other status tools like get_agent_status or get_benchmark_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use guidance: 'Use this to poll for completion after calling simulate_agent or simulate_ab_test.' It names the producing tools, but offers no when-not guidance (e.g., no note about how often to poll or what to do if the job never completes).

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 adds the aggregation scope ('across all diagnosed runs', 'fleet-level'), which is useful, but the rest enumerates return contents rather than behavioral traits like auth needs 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 sentences, front-loaded with the core purpose, then output contents, then usage cues. The output enumeration is a list but each item is informative and none is 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?

With no output schema, the description usefully describes what the aggregation returns (failure distribution, root causes, agent-type breakdown, suggestions), which compensates for the missing schema. Purpose, scope, and usage are all present; minor gaps only around sibling disambiguation.

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, so the description need not restate them. It adds no parameter syntax or semantics 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 and resource ('Get fleet-level step failure patterns across all diagnosed runs for an agent'), with an explicit scope that contrasts with single-run diagnosis tools. It does not name a sibling such as get_run_step_diagnosis or get_worst_run, so differentiation is implied by scope 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?

Gives concrete selection context via example questions ('what are my top failure patterns?', 'which agent steps are causing the most failures?'), which tells the agent when this tool applies. It stops short of naming alternatives or when-not-to-use conditions (e.g., single-run diagnosis).

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 adds real value by disclosing that the return is a URL to be consumed via EventSource rather than data itself, which matters with no output schema. It omits URL lifetime/expiry and auth requirements, so not 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 short sentences, zero filler, with the what (SSE stream URL) front-loaded before the how-to-consume instruction.

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 single-parameter read tool with no output schema, the description adequately explains what is returned (an SSE URL) and how to use it. Missing only minor operational details such as URL validity window or whether the stream terminates on process completion.

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?

Only one parameter with 100% schema description coverage ('The optimization process ID to stream'), so the schema already carries the semantics. The description adds no format, source, or constraint detail beyond what the schema states – 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+resource ('Get the SSE stream URL') and scopes it to real-time optimization updates, which distinguishes it from plain-read siblings like get_optimization_details and get_model_optimization_status. It does not name any sibling 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?

'Connect to this URL with EventSource for live progress' implies the usage context (live streaming rather than polling), but never states when to prefer this over the status/details siblings or any exclusions. Usage is implied rather than prescribed.

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 by structured data. The description adds one useful behavioral fact — that each trace may map to multiple runs in multi-agent setups — but says nothing about permissions, the superadmin customerId path, or result limits, so added value is modest.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.