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

Annotations only flag it as non-read-only, non-destructive, non-idempotent and open-world; the description goes far beyond by detailing the dry-run preview contents, the exact report shape, the 201/409 outcomes, that nothing is written without confirm, that adoption never refits, and that the run sits outside the attempt budget.

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 purpose, which is good, but the body is a dense run-on sentence with nested braces, semicolons and parenthetical issue codes that is hard to parse on a single read; every clause carries information, yet the structure could be split for scannability.

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?

An output schema exists, yet the description still supplies return details (201 {run, revision}, report fields, 409 conditions) plus the legacy/pre-snapshot edge case. It is near-complete for a mutation tool, with the unexplained 'reason' parameter the main remaining gap.

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

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

Schema description coverage is 0%, so the description must compensate: confirm is thoroughly explained (default false, preview semantics) and study_id/model_hash are implied by the surrounding narrative, but the required 'reason' parameter is never mentioned at all, leaving one of four parameters undocumented.

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 ('Import an owned completed model into a study as an executable, editable recipe') and immediately distinguishes itself from sibling write tools like create_study_recipe/create_recipe_draft by describing what it actually produces.

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 the two modes (preview without confirm vs. actual creation with confirm=true) and the 409 preconditions (model not complete, already attached). It names get_recipe_revision_authoring/create_recipe_draft as the follow-on editing path, but never explicitly says when to prefer this over create_study_recipe.

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 declaring readOnlyHint=false, openWorldHint=true and idempotentHint=false, the description adds substantial behavioral context well beyond the annotations: it appends an audit event, returns blockers and an evidence hash, substitutes null for older models, gates optional checks (retained_sampling, require_policy_review) with fallbacks like 'not_declared', and explicitly states decision_grade_ready stays false. These disclosures are consistent with the non-read-only, non-idempotent annotations.

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

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

The description is an unusually long, dense block of run-on sentences mixing many distinct topics (audit event, R-hat/WAPE, retained diagnostics, policy review, two provenance reports, fresh_validation). It is not front-loaded or scannable, and key routing/scoping information is buried mid-paragraph, so it exceeds what an agent needs to select and invoke the 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?

An output schema exists, so return values need not be restated, and the description does cover behavioral outcome states and gating logic richly. However, it leaves parameters entirely unexplained and gives no explicit alternative-tool routing, so it is adequate but with real gaps for a 4-required-parameter tool.

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

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

Schema description coverage is 0% and all four parameters (study_id, policy_id, full_run_id, validation_run_id) are undocumented in both schema and description. The prose references concepts like the 'declared protocol,' 'same-policy assessment,' and 'full-model revision' that gesture at the parameters, but it never defines what each id represents or how they interrelate, so it does not compensate for the coverage gap.

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

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

The description opens with a specific verb and resource ('Assess a validation pair and append a prediction-access audit event') and enumerates exactly what it inspects (MMM runs, frozen inputs, sampling, R-hat, WAPE, provenance). It also distinguishes itself from adjacent actions by stating it 'does not fit, accept or promote' and 'never clears champion blocks,' which separates it from launch/promote tools. It stops short of naming a sibling tool directly, so differentiation is inferred rather than explicit.

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

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

Usage conditions are implied heavily through the feature list (validation pairing, retainment, policy review, holdout/prior provenance, fresh_validation), but there is no explicit 'use this when / use X instead' routing to alternatives such as evaluate_study_run or get_study_validation_resolutions. The negative scoping ('does not fit, accept or promote') gives some when-not guidance, but an agent must infer the primary trigger from context.

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

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

Annotations already convey that this is destructive and non-idempotent. The description adds valuable behavioral nuance by clarifying that cancellation is a request and that 'requested' and 'confirmed stopped' are distinct states, implying an asynchronous or multi-step lifecycle. It does not contradict the annotations.

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

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

The description is extremely concise: two short sentences, with the key action upfront and the important state distinction immediately after. There is no filler or redundant restatement of the tool name.

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 destructive tool with an output schema and rich annotations, the description is mostly adequate. However, it does not explain the cancellation flow, how to confirm the eventual stopped state, or what side effects occur. The state distinction is a useful start but could be more actionable.

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 0%, and the description does not mention run_id at all. The parameter name is self-explanatory to a degree, but the description does not compensate for the lack of schema documentation by explaining what run_id refers to, how it should be obtained, or any constraints.

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 ('request') and a clear resource ('cancellation' of a study run), and it distinguishes the requested state from a confirmed stopped state. It does not explicitly differentiate it from sibling tools like update_run or get_study_run, but the core intent 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?

The description gives no explicit guidance on when to use this tool versus alternatives such as launch_study_run, get_study_run, or update_run. The state distinction hints at usage context but does not explain prerequisites, follow-up steps, or which sibling handles confirmed stopping.

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?

Far beyond the annotations, the description discloses crucial behavior: rows are comparable only when multiple dimensions match, incompatible rows are returned with the differing dimension in blockers and are never ranked, and serving prediction evidence appends access audit events. It also clarifies that no model fitting or promotion occurs, adding meaningful non-obvious context.

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

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

The description is dense but purposeful, with the core purpose front-loaded and supporting behavior details following. It is long, though each clause adds real value; a slight structural breakdown could improve readability, but 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?

Given that an output schema exists, the description need not explain return values, and it does a strong job explaining behavior, exclusions, and ranking semantics. The main gap is that study_id's meaning is left implicit, and since the schema gives no parameter descriptions, that missing piece prevents full completeness.

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 0%, so the description carries the burden. It implicitly explains run_ids as the 2-20 candidates and policy_id as the quality policy, but it never mentions study_id, its role, or any constraints on it. The description partially compensates for the bare schema but does not fully document all three required parameters.

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

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

The description opens with a specific verb and resource: 'Compare 2-20 candidates against one quality policy,' which is unambiguous about what the tool does. It further defines the output rows, comparability conditions, and explicitly scopes the tool to predictive ranking, making it distinguishable from nearby siblings like evaluate_study_run or assess_study_validation_pair even without naming them.

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 clearly states when to use the tool ('answers predictive ranking only') and gives explicit exclusions: sensitivity agreement is not computed, analyst acceptance lives in decisions, business validity is a human review, and it does not fit or promote models. It does not name alternative sibling tools, but the when-not guidance is strong enough for an agent to route correctly.

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 beyond annotations by naming the required auth scope, describing validation error behavior ('name the field'), and spelling out the consequence of non-idempotency ('calling twice records two tests', consistent with idempotentHint=false). It also notes that planned records carry no result. These add real behavioral context beyond the safety 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?

Front-loaded with the primary action and record contents, then progressively adds return shape, validation, idempotency, exclusion and scope. Dense but every clause carries information; only slight redundancy with annotations on idempotency.

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 complex nested-schema mutation with an output schema present, the description covers the design-block semantics, validation, scope, and the excluded time_holdout path. Return values are documented by the output schema, so omitting them is fine; a few minor behaviors (e.g. limits on record size) are not addressed but not critical.

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 only 50%, so the description must compensate, and it does: it explains what type selects (geo/owned_media_ab/platform_lift block), that dates are YYYY-MM-DD, that measured_through defaults to end_date, that lift_abs is total lift in KPI units, that null/negative lifts are valid, and that spend.incremental is signed. This meaningfully supplements the nested schema.

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

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

States a specific verb+resource ('Record one incrementality test in a project') and immediately scopes what a record contains (design block, dates, KPI, result, spend). It also names a sibling it is NOT: 'type time_holdout is not accepted here... created only through save_incrementality_test_design', letting an agent distinguish it from nearby tools without opening 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?

Explicit when-not guidance: time_holdout is refused here and must go through save_incrementality_test_design. It also states the required scope ('create:models') and the setup condition ('Set model_channel to the model activity column the test calibrates'). No alternatives are 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 only declare it is a non-readonly, non-idempotent, open-world write. The description goes far beyond: async return contract, the model starting 'unsaved — invisible to list_models,' the silent-failure trap where a margin key placed in a config dict is ignored, strict 400 rejection of unknown keys, and calibration_refused 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?

Purpose, async contract, and polling guidance are correctly front-loaded, but the Args section runs to roughly two thousand words with internal issue numbers (#632, #672, #630) and dense register detail that a caller must wade through. Much is justified by genuine complexity, yet it is not scannable and could be trimmed.

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

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

For a 26-parameter fitting tool with an output schema, this is complete: required inputs, defaults, cross-parameter constraints (operating_margin vs operating_margin_column, generalized_log anchor combinations), and downstream verification paths are all covered.

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?

With schema description coverage at 0% and 26 parameters, the description carries the entire burden and does so: it documents every argument, including enum-like values for likelihood/saturation_type/link/attribution, total_media_effect industry benchmarks, the three mutually exclusive saturation-anchor forms, transform units, and rejected key aliases.

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?

Opens with a precise verb+resource: 'Create and start fitting a new Bayesian Marketing Mix Model,' which distinguishes it from sibling creation tools (create_var_model, create_study). The async semantics ('queues an async model fit and returns immediately with a model_hash') further pin down what this tool uniquely does.

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 next-step context ('Use get_model_status to poll for progress until status is complete') and workflow prerequisites via upload_data, save_model, and calibration. It doesn't explicitly state when to choose this over sibling creation paths (e.g., a study recipe), so it stops short of full 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?

The description adds substantial behavior beyond annotations: name sanitization rules, team membership requirements with distinct 403/404 errors, and the 201 response including the created project id. Annotations already indicate a mutating, non-idempotent operation, and the description is consistent with them.

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

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

The description is concise, front-loaded with the core purpose, and organized into clear sections: purpose, sanitization note, Args, and Returns. Every sentence adds distinct value with no repetition of schema or annotation information.

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

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

For a two-parameter creation tool with an output schema present, the description covers the essential behavior: display name, sanitation, team-sharing constraints, return status, and how the result connects to save_model. No critical calling information 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 0%, but the description fully compensates by explaining both parameters: 'name' as a display name and 'team_id' as optional sharing with an owned team, including error semantics. This adds real meaning beyond the bare schema types.

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 and resource: 'Create a named project (model folder) to file models into.' This clearly distinguishes create_project from sibling tools like create_model and create_recipe_draft by establishing that a project is a container for models.

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: projects are for filing models into, and the returned id is meant to be passed to save_model(project_id=...). It does not explicitly name alternatives or when-not-to-use conditions, but the workflow hint is strong enough to guide appropriate invocation.

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

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

Discloses far beyond sparse annotations: immutability of saved policies, refusal behavior ("the refusal names the count", "refused with one message naming its position and declared kind"), backend validation of rules, agent restrictions ("cannot submit manual sign-off"), provenance edge semantics ("blocked fails, absent is not_collected"), and response contents (diff carrying checks/protocol changes). No contradiction with readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false.

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

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

Front-loaded with purpose ("Save project-specific checks") followed by the most decision-relevant constraint (immutability). The description is long (~400 words) but each sentence carries distinct rules for a genuinely complex tool — check taxonomy, constraints, error behavior, protocol. Minor redundancy exists with the checks item description already embedded in the schema (e.g., "At least one required gate per policy; at most 20 checks"), so it is not maximally lean.

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

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

For a 6-parameter tool with zero schema descriptions, the description is remarkably complete: every check kind and its expression, validation invariants (at least one required check, each metric once, max R-hat ≥ 1, ≤20 checks, no default thresholds), prediction-window semantics, validation protocol semantics, lineage/diff behavior, and error/refusal format. The output schema covers return values, so nothing an agent needs to invoke 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 0%, putting the full burden on the description, and it delivers: categorizes the metric enum into built-in/artifact-backed/custom with per-kind parameter requirements (operator defaults like lte, custom:<slug> syntax, boolean vs manual shapes, expected semantics), explains validation_protocol as a temporal holdout split with configured sampling intent, and clarifies derived_from_policy_id lineage. This far exceeds the bare schema titles.

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?

"Save project-specific checks" states a specific verb (save/create) and resource (project-specific quality policy), and the immutability clause immediately establishes this as the creation tool in a create/list/get/diff/retire family. An agent can distinguish it from diff_quality_policies, list_quality_policies, get_quality_policy, and retire_quality_policy without opening 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?

Gives explicit when-to-use context: "Policies are immutable: to change one, create a new policy, ideally with derived_from_policy_id naming the saved policy you started from (same study)" — this defines the derivation workflow clearly. However, it never names sibling alternatives (retire_quality_policy for retiring, diff_quality_policies for comparing) nor states explicit when-not-to-use conditions, so it falls 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?

Adds substantial context beyond the annotations (readOnly=false, idempotent=true, destructive=false, openWorld=true): the idempotent replay contract (reuse identical draft_id), target immutability with specific 409/404 semantics, and backend version/size validation. The description's write/idempotent behavior is fully consistent with 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?

Front-loads the core purpose before extending into the mode-switching rules, and every sentence carries load (idempotency, target vs branch, error codes). It is dense and long, which slightly raises parsing effort, but there is little pure 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?

An output schema exists so return values need not be explained, and the description covers the full complexity of the two draft modes, the template entry points, and replay semantics. Minor gaps remain around name/study_id scoping, but nothing that would cause a mis-invocation.

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

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

With only 17% schema description coverage, the description compensates well for the complex parameters: target becomes an edit session with an immutable recipe link, source_revision_id branches into a new recipe scoped to the study, and draft_id is a reusable UUID. It leaves name, study_id, and snapshot body undocumented, but those are self-evident or covered by nested schema field descriptions.

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

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

States a specific verb and resource ('Save an encrypted authoring draft') plus the distinguishing constraint that it neither publishes nor consumes an attempt. It explicitly differentiates itself from siblings like get_recipe_draft_template, get_recipe_revision_authoring, and publish_recipe_draft, so an agent can tell the modes apart.

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

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

Gives explicit when-to-use routing: start from get_recipe_draft_template for a new draft, from get_recipe_revision_authoring when working from a published revision, pass target to edit in place, or omit target and supply source_revision_id to branch. The alternative paths and their selecting conditions are spelled out, not 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 flag this as a non-read-only, non-idempotent create operation, and the description adds valuable behavioral detail: creation has no launch side effects, does not consume attempts, and the question is stored for humans rather than executed. No contradiction with annotations.

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

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

The definition is front-loaded with the main purpose and scoping, and the example question is useful. It is a single dense paragraph without filler, though some content repeats what is already in the schema descriptions.

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 create tool with an output schema and annotations covering safety, the description covers purpose, ownership, side-effect absence, and question constraints well enough to invoke correctly. It does not fully explain max_attempts/max_concurrent semantics, but those have defaults and are named in the run-limits guidance.

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

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

Only 2 of 6 parameters have schema descriptions (33% coverage), so the description needed to compensate; it does well for question and context, including what belongs elsewhere. However, max_attempts and max_concurrent are only referenced as places for run limits, and name/project_id receive no semantic detail, leaving meaningful gaps.

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'), the resource ('a study'), and the ownership constraint ('owned by an existing project'), and immediately differentiates itself from related actions by noting it does not launch models or consume attempts. This makes it clearly distinct from siblings like launch_study_run and update_study.

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 guidance on what this tool is not for: it does not launch models or consume attempts, and it explicitly routes acceptance thresholds and validation rules away from the question field to quality policies, recipe revisions, and max_attempts/max_concurrent. It stops short of naming sibling tools like update_study or launch_study_run as explicit alternatives.

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

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

Annotations cover the write/non-idempotent/non-destructive profile, and the description adds real behavior beyond them: a hash mismatch returns 409 and forces a fresh preview, and model_snapshot is review-only (launch refused, lineage unknown). It does not state permission/auth requirements, but the mutation semantics and failure mode are well disclosed.

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

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

Four dense sentences, each carrying distinct information, with the core purpose front-loaded. No filler, though the spec-kind sentence packs multiple constraints into one line.

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

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

For a write tool with a nested spec object, an output schema (so returns need no explanation), and rich annotations, the description covers the key branching (kind selection), the ancestry concern, and the 409 failure path. Only the untouched scalar params keep 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 description coverage is only 17%, so the description must compensate, and it does add meaning for source_revision_id and expected_content_hash that the schema lacks (titles only). It leaves name, reason, and study_id unexplained, so roughly half the parameters remain undocumented.

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?

Opens with a specific verb+resource: 'Freeze a recipe without fitting', which pins down the operation and distinguishes it from fitting/authoring. It doesn't name the sibling tools it replaces (create_recipe_draft, publish_recipe_draft), but 'freeze' vs 'draft'/'fit' is inferable.

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 conditional guidance for source_revision_id ('when deriving from a published same-study recipe') and for choosing between api_mmm and model_snapshot kinds. However, it never states when to use this tool versus create_recipe_draft, revise_study_recipe, or refreeze_recipe_revision, so tool-selection 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 declare readOnlyHint=false and destructiveHint=false, indicating mutation but no destruction. The description adds important behavioral details: it returns a 202-style payload with model_hash, requires polling get_model_status, and notes that unknown keys in var_priors are rejected. It also specifies that fitting starts asynchronously, which is beyond what annotations provide. No contradiction with annotations.

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

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

The description is long but well-structured with a purpose statement, contextual background, a detailed Args section, and a Returns note. Each sentence serves a purpose, explaining either the tool's role or parameter constraints. It's slightly verbose but justified given the 12 parameters and the need to compensate for zero schema coverage. The key 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?

Given the complexity (12 params, no schema coverage, mutation, asynchronous behavior), the description is remarkably complete. It covers prerequisites (dataset content, row count), parameter relationships, defaults for optional params, and the return type with follow-up action. Nothing an agent needs to invoke 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 0%, so the description carries the full burden for parameter documentation. It explains every parameter in the Args section, adding meaning well beyond the schema: e.g., uploaded_file_id must contain every named column, date_column cannot also be a series, endogenous_vars must have at least two, lags requires enough rows, base_variable must be endogenous, etc. This is essential for correct invocation.

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

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

The description clearly states the action: 'Create and start fitting a long-term (VAR) model'. It distinguishes itself from the sibling link_var_model by explaining that this tool creates the model while link_var_model connects it to an MMM. The reference to the MMM's long_run_rollup gives domain context.

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

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

The description provides clear context for when to use this tool: for modeling joint dynamics of series and producing long-run elasticity. It explicitly mentions the follow-up step of linking with link_var_model, which guides the agent on the workflow. However, it doesn't explicitly state when NOT to use this tool or list alternative model-creation tools (like create_model), so it's not fully explicit about 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 provide idempotentHint and readOnlyHint=false, and the description adds behavioral context beyond them: write-scope requires project-owner credentials and create:models, declaration_id idempotency mechanics, revocation of stale revision influence, and the fact that API declarations stay marked as reported. This is rich behavioral disclosure with no contradiction to the annotations.

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

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

The description is dense but every sentence earns its place by adding an operational constraint or clarification. Core purpose is front-loaded, followed by prerequisite steps, retry behavior, parameter conditions, and exclusions, 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?

Given a non-trivial six-parameter mutation with zero schema descriptions, the description covers prerequisites, auth, idempotent retry, conditional parameter requirements, validation implications, and non-goals. An agent has enough context to call this tool correctly and to understand follow-up obligations such as fresh validation.

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 0%, so the description carries the full burden, and it succeeds: declaration_id is tied to fresh-UUID/retry semantics, source_access_id to an access event from the run, disposition and affected_revision_id to the informed_revision conditional, and reason to explaining actual use. Every parameter receives meaningful semantic guidance beyond its bare title.

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

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

The opening phrase 'Append a submitter-reported evidence-use declaration' names a specific verb, resource, and scope, and the final sentence explicitly excludes certification/promotion duties, differentiating this from sibling study actions. It also names get_study_prediction_access as a prerequisite, which helps distinguish the read path from this write path.

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

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

The description gives explicit when-to-use instructions: read get_study_prediction_access first, reference an access event from this run, and use a fresh UUID reused unchanged on retry. It also states conditional usage rules for informed_revision versus other dispositions, giving clear operational guidance without requiring the agent to guess.

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 mark this destructive and non-read-only, but the description adds meaningful context: deleting is irreversible, unlinks MMMs pointing to the model, removes stored artifacts, and returns a specific success payload. It also discloses the 409 error behavior for non-failed models. No contradiction with annotations exists.

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 dense but every sentence earns its place: scope, irreversibility, precondition, side effects, return value, and pre-check advice are all included. The most critical warning is front-loaded, and the Args section is clean.

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 one-parameter API, the description covers allowed inputs, error conditions, side effects, success response, and recommended pre-checks. Even with an output schema present, it explicitly shows the success payload, leaving little for an agent to guess.

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?

With 0% schema description coverage, the description carries the full burden. It defines model_hash as the hash of the FAILED model to delete permanently, adding the critical status constraint and purpose beyond the schema's bare 'Model Hash' title. It could mention how to obtain the hash or confirm its format, but for a single parameter this is adequate.

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

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

The description states a specific verb and resource ('PERMANENTLY DELETE a FAILED model') and clearly scopes the operation to failed models only. This distinguishes it from sibling tools like get_model, rename_model, or unlink_var_model, even without inspecting 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?

The description explicitly says when to use the tool: only for failed models, and explicitly states that any other status returns a 409. It also advises checking with get_model or get_model_status first, giving an agent clear decision 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?

With annotations already covering idempotency and safety, the description still adds substantial behavior: 202 vs 200 response semantics, submission_key replay rules, the 409 submission_key_conflict, refusal codes (404, 422, 503 queue_unavailable with nothing left behind), and the permission model (create:models to submit, read:results to poll). It also enumerates result states (available/unsupported/insufficient_evidence/no_feasible_design) and clarifies none are errors. No annotation is contradicted.

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 return shape and the queue/poll model are front-loaded, and almost every sentence carries operational content. It is dense and long, with error and permission details packed into trailing run-ons, so it is information-rich but not maximally scannable.

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

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

Given a 7-parameter nested schema with low coverage, an output schema, and mutation-adjacent semantics, the description covers return body, status lifecycle, result states, defaults, error codes, and auth requirements. An agent has everything needed to submit, poll, and handle failures.

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 only 29%, so the description must carry the load, and it does: channel must be a nonlinear media channel (400 unknown_channel), design_type semantics for time_holdout vs geo_split, the full intervention contract (start_date window, 1-8 durations, spend_change modes, baseline requirement), and inference defaults that are echoed. This adds meaning well beyond the raw schema.

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

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

The description opens with a specific verb and resource: ask a saved, complete MMM what an incrementality test on one of its media channels could detect, and immediately frames it as a bounded queued calculation. It is clearly distinguished from siblings like get_incrementality_test_design (polling) and save_incrementality_test_design (persisting), so an agent can route correctly 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?

It names the follow-up tool (get_incrementality_test_design) and the persistence path (save_incrementality_test_design), plus the explicit constraint that nothing is saved or launched and no budget changes. Usage context is strong but it never explicitly contrasts this with the sibling create_incrementality_test, leaving the design-vs-launch boundary inferential.

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 signal readOnly and non-destructive; the description reinforces this with 'Read scope; nothing is written' and adds substantive behavioral detail: matching is by metric so reordering is not a change, rules comparison is hash-based, and the direction from → to is meaningful. No contradiction with annotations.

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

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

Three dense sentences front-load the operation and diff semantics, then add lineage/use-case context. No filler or repetition of schema fields.

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

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

The description explains the operation, directionality, diff semantics, read-only behavior, and use cases. Output schema exists and annotations cover safety, so nothing needed for calling the tool 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?

With 0% schema description coverage, the description must carry parameter meaning, and it does: it defines policy_id as the source saved policy, other_policy_id as the target, and notes they must be in the same study. It does not explicitly describe study_id, but the phrase 'same study' and the parameter name make it clear.

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

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

Description opens with the precise operation: computing changes between two saved policies in the same study. It enumerates concrete diff dimensions (checks, protocol fields, name_changed, rationale_changed, rules_changed), which clearly distinguishes it from get_quality_policy and list_quality_policies.

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 use cases: explaining lineage via get_quality_policy.derived_from and comparing policies before selecting one. It names a sibling (get_quality_policy) as related, but does not explicitly state when this tool should not be used.

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/idempotent/non-destructive, and the description adds genuine operational context: a 404 when the recipe or either revision is missing, the "blank equals absent" convention, and that prior rows are matched by variable and role. Return-format details duplicate the output schema, but the error and matching semantics are real additions.

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 answer, but a large share of the text enumerates the return payload (settings[], priors[], data, counts) that the output schema already defines, which is wasted space. Dense but not efficient.

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

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

Covers error behavior and edge semantics for a read-only three-parameter tool, and the output schema handles return values. The main remaining gap is that the three required input parameters are never described, leaving their meaning to inference.

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 0%, so the description must carry the parameter burden. It implies base/other are the two revisions being compared and that recipe_id scopes them, but gives no types, ordering rules, or which is "from" vs "to". Partial compensation only.

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 (diff) and resource (two revisions of one recipe) with the exact scope of comparison. An agent can distinguish it from diff_quality_policies and compare_study_runs without reading 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?

"Read this after publishing revision N+1 to state exactly what an edit changed" gives clear timing/context for use. It does not name alternatives (e.g. get_recipe_revision for a single revision) or state when not to use it, so it stops short of the top score.

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

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

The description goes well beyond the annotations. It discloses that preview writes nothing and creates no access event, that stale evidence returns 409 stale_evidence, that external calculations are submitter-reported and not verified, that carried rows keep carried_from provenance, that manual sign-off is never carried, and that built-in errors are fitted-window not holdout. These are behavioral traits an agent needs to know and are not present in the annotations.

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

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

The description is dense and information-rich, with the most important behavioral facts front-loaded (immutable save, preview mode, no write). Every sentence adds a distinct fact, but the density is high and some sentences are packed with multiple clauses that require careful parsing. It is appropriately sized for the tool's complexity, though slightly less structured than ideal.

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

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

Given the tool's complexity (6 parameters, preview vs. write modes, carry-forward rules, error conditions, provenance semantics), the description covers the critical operational context: what happens on write, what preview returns, what causes 409, what is never carried, and what is unsupported. The output schema exists, so return values need not be described in detail. The description is complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain the key parameter semantics: preview=true means no write, expected_basis_hash comes from the preview, carry_forward requires the metric to be listed under carry_forward_available, and external_evidence requires finite numeric or strict boolean values with method and source_reference. However, it doesn't explicitly map every parameter (e.g., run_id, policy_id) and doesn't explain the policy_id choice beyond 'Choose policy_id explicitly; the report echoes policy_name and policy_was_newest.' Still, the description adds substantial meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Save an immutable assessment, or with preview=true see what one would contain without writing.' This clearly distinguishes the two modes of the tool and names the resource (assessment of a study run). It also differentiates from siblings like list_study_evaluations and recommend_study_run by describing the write/preview behavior.

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

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

The description gives explicit when-to-use guidance: use preview=true to see what an assessment would contain without writing, and use the full submission to save. It also states exclusions: 'Manual sign-off is never carried and requires a signed-in reviewer,' 'VAR remains unsupported,' and 'No automatic champion promotion.' These exclusions help an agent decide when not to use this tool or what not to expect.

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

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

The description goes well beyond the annotations: it explains open-world semantics ('missing advertisement is unknown, not unsupported'), warns that advertised features still require permission and budget, and discloses that no model is created and capabilities are not cached across callers. This meaningfully informs how the agent should treat the result.

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

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

Four compact sentences, each earning its place: when to use, what it returns, how to interpret missing/advertised features, and what side effects to expect. The key guidance 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?

With zero parameters, rich annotations, and an output schema present, the description is fully sufficient for an agent to select and invoke the tool correctly. It covers timing, interpretation, permission nuance, and non-caching 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?

There are zero parameters, so the description carries no parameter burden. The baseline of 4 applies, and the description still helps set expectations about what the returned result represents.

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 and resource: 'Discover this caller's connected backend features' and clarifies it returns only backend advertisements for model families, transformations, priors, and workflow operations. This clearly differentiates it from the many sibling tools by scope and intent.

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

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

It explicitly says to use this before planning work and explains how to interpret missing advertisements ('unknown, not unsupported'). It does not name exclusions or alternative tools, but none of the siblings compete with this capability-discovery role.

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

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

Annotations cover only the read-only/idempotent safety profile, and the description adds a great deal beyond them: the core grain-assumption and its bias direction, method variants (attribution_scaled vs spend_share), factor_source override semantics, the 'pending' interval background-job behavior ('ask again in a few minutes'), nulling rules for platform_value_missing, and error codes. This is unusually rich behavioral disclosure.

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

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

The purpose and the crucial assumption are front-loaded, but the description then enumerates the entire return payload (channels/rows/unmapped/provenance fields) and the full warning-code list even though an output schema exists and already documents return values. That redundancy makes it considerably longer than necessary for its job.

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 methodology-heavy analytical tool, the definition covers the assumption, method provenance, interval lifecycle, warning semantics, error codes, and parameter defaults. Nothing an agent needs to call it correctly or interpret its output caveats 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 0%, so the description must carry the burden and does: model_hash is defined as 'A fitted MMM with a campaign map (set_campaign_mapping)', start/end as inclusive ISO dates defaulting to the data/facts overlap, and level's campaign default with ad-set inheritance and summing behavior.

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

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

The opening line names a specific verb, resource and scope: 'Incremental ROAS per campaign (or ad set), beside the platform's own ROAS and last-click ROAS.' It further distinguishes the tool from siblings like get_campaign_report and get_incrementality_test by explaining the attribution-scaling methodology that is unique to this endpoint.

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

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

The description gives strong contextual guidance and even routes the agent elsewhere when the assumption is violated ('map them to their own model channel (set_campaign_mapping) or to calibrate the factor with an incrementality test'), plus the key caveat 'Nothing here is a causal per-campaign measurement.' It stops short of an explicit when-to-use-this-vs-that comparison against get_campaign_report, so it is clear context rather than full 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?

Beyond the annotations (readOnly/idempotent/openWorld), the description discloses substantive behavior: how campaign shapes are derived (rescaled by spend share and relative efficiency), that daily spend is observed spend over inclusive calendar days rather than a configured budget, that missing currency/curve/fact coverage yields unavailable recommendations, and that absent posterior evidence means no interval rather than zero uncertainty. It also confirms no fit or platform change is triggered.

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, then Args, then Returns, so structure is strong. It is somewhat long and the 'no fit, posterior job or platform change is started' clause partially overlaps the readOnly annotation, but most sentences carry genuine, non-redundant information.

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

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

For a read-only analytical tool with four params and an output schema, the definition is complete: prerequisites, input semantics, caveats on what the numbers do and do not mean, and failure behavior are all covered, and it even summarizes the return shape despite an output schema existing.

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?

With 0% schema description coverage, the description carries the full burden and delivers: model_hash must be an owned, completed MMM with compatible provenance; start/end are inclusive ISO dates (YYYY-MM-DD); level is campaign or adset with ad sets inheriting the campaign's channel. All four parameters get meaning the bare schema lacks.

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

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

The opening sentence names a specific verb and resource (read channel-derived marginal returns for campaigns or ad sets) and delimits scope against adjacent concepts by stating these are 'not independently measured campaign saturation curves or causal campaign effects.' It does not name a sibling tool directly, 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?

It states a precondition ('Requires read:models') and constrains model_hash to an 'Owned, completed MMM with compatible curve provenance and campaign facts,' plus a 'do not substitute defaults' rule on missing data. However, it never says when to prefer this over neighbors like get_campaign_report, get_campaign_incrementality, or recommend_campaign_budgets, so 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, idempotentHint, destructiveHint=false), and the description adds substantial context beyond them: the 'unmapped' group guarantee that spend is 'never dropped or guessed into a channel,' the meaning of as_of and source_versions, and the error codes with their HTTP statuses and remediation. This is exactly the extra behavioral detail 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?

Front-loaded with the purpose and sibling contrast, then a Returns block, then an Args block that mirrors the schema. Every sentence carries information, but the return-shape paragraph is partially redundant given an output schema exists, and the Args block, while necessary at 0% coverage, makes the definition long.

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

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

For a 9-parameter, zero-required aggregation tool this is complete: purpose, metric availability caveats ('where a source fills them'), grouping edge case, return shape, defaults, and error taxonomy are all present. An agent has everything needed to call it correctly without further exploration.

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 0%, so the description must carry all nine parameters, and it does: model_hash (and its dependency for group_by=channel), start/end inclusivity, granularity semantics, group_by values with the 'unmapped' behavior, filters applied before grouping, and a metrics example with default. It adds meaning the schema cannot express, such as what happens without model_hash.

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 ('report the campaign facts over any window, at any grain') and pins down the exact metric set (spend, media:impressions, media:clicks, platform conversions/value). It explicitly differentiates itself from siblings by naming get_data_report as the same engine over a different fact table, and from get_campaign_incrementality by noting these are 'the PLATFORMS' own attributed numbers, not Simba's incremental attribution.'

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

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

Gives clear context for when to reach for this tool (platform-attributed campaign facts reporting) and contrasts it against incremental attribution, which routes the agent away from get_campaign_incrementality. It also documents the error cases and the remediation ('narrow the window or coarsen the granularity'). It stops short of an explicit 'use X instead when…' rule for get_data_report beyond the fact-table distinction.

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 readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is disclosed. The description adds 'Legacy dashboard-saved configs are served verbatim,' which is a behavioral nuance beyond the annotations, but it is terse and cryptic ('#436') and does not explain implications like formatting or transformation.

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 short (two sentences) and front-loads the purpose, which is good. However, the second sentence is cryptic and not well structured; it references '#436' and a legacy behavior without context, making it less clear and slightly wasteful.

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

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

For a simple read tool with one parameter and an output schema, the description is minimal. It omits any explanation of the model_hash parameter and does not mention potential error cases or prerequisites. The cryptic legacy note adds confusion rather than completeness. The output schema exists, so return values are not required, but parameter description and edge cases are missing.

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

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

Schema description coverage is 0%, and the description does not mention the model_hash parameter at all. The parameter is named model_hash, which is somewhat self-explanatory, but the description adds no meaning about its format, requiredness, or how to obtain it. With zero coverage, the description must compensate, and it does not.

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

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

The description clearly states the tool reads stored contribution groups for a model, using the verb 'Read' and naming the resource. It distinguishes from the sibling set_contribution_groups, though it does not explicitly name that sibling. The reference to '#436' is cryptic and not helpful.

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

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

The description implies usage (reading contribution groups) but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It does not mention that set_contribution_groups is the write counterpart or any conditions that would route an agent here.

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 (readOnly/idempotent/non-destructive): it documents aggregation rules, bucket semantics (ISO week from Monday, weekly rows counted in the month of week-start), the meta.aggregation disclosure, and specific error codes with statuses (404, 400, 413 with the 10,000-row cap and remediation). This is exactly the extra behavioral 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?

Front-loads purpose and routes the reader through clearly labeled sections (roles, buckets, args, returns). It is dense and long, but given 0% schema coverage most of the length is load-bearing; only minor tightening is possible.

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

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

Covers the full lifecycle an agent needs: correct invocation, role declaration fallback, aggregation semantics, return shape, and error handling. Since an output schema exists it wisely only summarizes the return structure rather than fully restating it.

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 0%, so the description carries the full burden, and it does: all 8 parameters are explained in an Args block (dataset_id origin, inclusive ISO start/end, granularity values, group_by options, hierarchy filter, metrics defaults, roles override format). It additionally supplies the role vocabulary and channel-qualified role syntax that the schema does not encode.

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 ('Report actual data from a stored dataset') with explicit scope ('any window, any grain, by brand, channel or dimension'). It also distinguishes itself from the model-based alternative by noting it 'Reads the dataset itself ... rather than a fitted model's training window', which separates it from siblings like get_model_results and get_data_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 usage example ('sales and TV spend in the North region for August, by week') and implies the read-raw-data-vs-model distinction, plus the prerequisite that roles must be declared via upload_data(roles=...) or per request. It never explicitly names a sibling to avoid the way a 5 would, so guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the tool's return contract: a JSON Schema specification listing required columns, naming conventions, constraints, and date formats. No contradiction exists, and the behavior is fully consistent with a read-only metadata query.

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 compact and front-loaded: the first sentence states the action and resource, and the second sentence enumerates the return contents with no wasted words. Every sentence contributes useful information, and the structure is easy to parse quickly.

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 no-parameter, read-only schema tool with an output schema, the description is complete. It tells the agent exactly what to expect in the response, lists the schema's key contents, and needs no additional context to select or invoke the tool correctly.

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

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

The tool has zero parameters, so the input schema is trivially documented at 100% coverage. There are no parameter semantics for the description to clarify, and the baseline for zero-parameter tools is 4; the description appropriately focuses on the return value instead.

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

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

The description states a specific verb and resource: 'Get the canonical CSV data schema for Simba MMM input files.' It further clarifies the exact content returned (required columns, naming conventions, constraints, date formats), leaving no ambiguity about what the tool does. It is clearly distinguishable from all siblings, none of which offer a data 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 provides clear context: this is the canonical schema for Simba MMM input files, which signals when an agent should call it for constructing or validating input data. It does not explicitly name exclusions or alternatives, but no sibling tool serves the same schema-retrieval purpose, so the implicit use-case guidance is adequate.

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/idempotent/non-destructive, and the description adds substantial behavioral context beyond them: the calibration success vs. refusal shape, the enumerable refusal reasons, and the required read:models scope. This is unusually rich disclosure for a read 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?

Dense but front-loaded: purpose first, then version, then the model_hash/calibration branch, then refusal handling and scope. Every clause carries meaning, though the inline brace-listing of base record fields is somewhat redundant against the output schema and adds bulk.

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 a required scope, a rich conditional output (calibration), and five params at 0% schema coverage, the description supplies everything needed: id/version semantics, the model_hash branch, refusal enumeration, and cross-tool linkage. With an output schema present, it need not do more.

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 0%, so the description must carry the load, and it does: version (older version, default current), model_hash (a saved model you can read, triggers calibration), channel (a model activity column, passed for channel_not_in_model), and confirm_kpi (pass true only if the test's outcome really is the model's KPI). Four of five params are given real semantics.

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

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

States a specific verb+resource ('Read one recorded test') and enumerates the record shape ({id, version, record, content_hash, used_by, retired_at}), which cleanly distinguishes it from the sibling list_incrementality_tests (singular fetch vs. list). An agent can pick this tool without opening another 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 usage context: version reads older versions (default current), model_hash enriches the result, and refusals are answers not errors with named remediations. It cross-links to create_model(calibration={tests: [...]}). It stops short of an explicit 'when-not/what-alternative' statement (e.g. pointing to list_incrementality_tests to find ids), so not 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 declare readOnly, idempotent and non-destructive, so safety is covered. The description adds genuinely useful behavioral context beyond the schema: the read:results permission requirement and the non-obvious rule that result must be read by its own state rather than key presence, with defined state 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?

The description is a single dense run-on paragraph that buries the operation's purpose behind an exhaustive payload enumeration. It is information-rich but poorly structured and far longer than needed given that an output schema already exists.

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

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

Given the complexity and the presence of an output schema, the description is thorough about state semantics, error codes, auth requirements and the caveats around power/model-implied effect. The main gap is that it never grounds the two required identifiers.

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 0% and the description never defines model_hash or calculation_id beyond echoing them as output fields. It does not say where these identifiers come from or how they relate, so the description fails to compensate for the coverage gap on the two required params.

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

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

States a specific verb and resource ('Read one test-design calculation') and lists the identifying fields and payload shape, so an agent can tell it is a singular retrieval of a design calculation. It does not, however, explicitly differentiate itself from siblings like design_incrementality_test or get_incrementality_test.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives. The only usage signal is the trailing 'Requires read:results' permission note; the agent must infer the workflow position from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces this with 'Read' and 'Consumes nothing.' It adds genuinely non-obvious behavior beyond annotations: the policy selection rule ('newest active when policy_id is omitted') and the disclosure that the revision comes back with its engine state. It doesn't fully cover auth requirements or rate limits, but for a read-only tool with full annotation coverage, the description adds meaningful value.

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

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

The core purpose is front-loaded in the first clause, followed logically by returns, safety, and the special-case workflow. The enumeration of ten blocker codes is long, but each is a stable contract value agents need for downstream branching; it borders on redundancy with the output schema but earns its place overall.

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

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

For a 3-parameter read tool with a rich annotation set and an output schema, the description is unusually complete: it covers purpose, when to call it, what it returns, safety ('Consumes nothing'), the policy default, and the one critical post-call workflow branch (engine_changed). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the only non-obvious parameter, policy_id, including its omission behavior ('newest active when policy_id is omitted'), and clarifies what revision_id yields ('the revision with its engine state'). study_id is left to name inference, but given the tool's pre-launch context, it is trivially inferable. This is strong compensation for a 0%-coverage schema.

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

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

States a specific verb and resource: 'Read, before launching, exactly what launch_study_run would refuse with.' It enumerates the precise deliverable (can_launch plus blockers with stable codes, messages, next_action), which distinguishes it from its siblings launch_study_run (the mutation it preflights), get_study_run, and get_recipe_revision. The first clause alone would differentiate it; the detail makes the purpose unmistakable.

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

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

Gives an explicit temporal trigger ('before launching'), names the sibling it pairs with (launch_study_run), and provides a concrete conditional routing: 'For engine_changed, call refreeze_recipe_revision and launch the new revision; never retry the old one.' The 'never retry' clause is an explicit when-not, which is rare and valuable.

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 mark this as read-only and idempotent. The description adds substantive behavioral detail beyond that: it works for any status, the error field is non-null only for failed models, and it lists the configuration echo and its known omissions. This materially helps an agent predict behavior without over-claiming.

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 organized: opening purpose, use cases, returns, and a note about omissions. Every sentence carries useful information, including the critical caveat about omitted create_model inputs. The most important differentiator (works for any status) 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?

Given the simple one-parameter input, the existing output schema, and the annotations, the description covers all decision-relevant details: why to use this over siblings, what the return shape means, and an important limitation of the echo. No critical gap remains for safe invocation.

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

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

The schema only provides the parameter name and type with 0% description coverage. The description's Args section adds 'The model hash (any status),' clarifying that this identifier is valid even for failed models. For a single parameter this is adequate, though more detail on how to obtain the hash could be helpful.

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

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

The description begins with a specific verb and resource: 'Get a model's metadata and configuration echo.' It clearly states what the tool returns and explicitly contrasts itself with get_model_results, making its scope unambiguous and differentiating it from a close sibling.

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

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

It gives explicit when-to-use guidance: 'works for EVERY status, including failed models' and contrasts with get_model_results which 'needs complete.' It also explains common use cases: inspect configuration, understand failure, or locate a model. This is direct and actionable.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false; the description explains the side effect ('serving it appends an access audit event' for study-linked models), which is consistent and clarifying. It also discloses non-obvious behavior well beyond annotations: opt-in sections never in the default payload, feature-detect patterns ({available:false, reason:...}), no backfill for pre-#629 fits, oversize results returning an actionable error rather than partial evidence, and that local filtering does not bound backend downloads.

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

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

Well organized with headers, bullets, and front-loaded purpose, but grossly over-long for a tool description — the per-section prose plus issue-number archaeology (#509, #452, #591, #629, #643) and edge-case narrations push it well past what an agent needs to select and invoke correctly. Structure is good; size is not.

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

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

For a 9-parameter tool with ~20 sections, the description covers everything needed: channel-key naming (activity column vs channels[].name), date windowing semantics and meta.not_windowed, filter scope, feature detection for absent artifacts, and the trust-sections_available-over-docs rule. An output schema exists, yet the section shapes are also described, leaving no ambiguity about what comes back.

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 0%, so the description carries the full burden and does: sections (comma-separated, empty = all, common combos), format (json/csv and the exact CSV return shape), channels (case/space-insensitive matching, suffix tolerance, which sections it applies to, and that contributions is never filtered), max_response_bytes, max_grid_points striding rules, start/end inclusivity, and granularity values.

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?

Opens with a specific verb+resource ('Get results from a completed model') and then enumerates the exact sections available, so an agent knows precisely what surface this covers. It does not, however, explicitly differentiate itself from close siblings like get_model, show_response_curves, or show_decomposition — it only cross-references get_optimizer_results and get_scenario_results for two sub-sections.

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?

Explicit when-to-use guidance throughout: which sections are opt-in only (mroi_periods, prediction_window), 'Always read channel_summary first to get the exact keys', 'Use coefficients for per-period revenue', and an explicit routing rule to get_data_report for data outside the training window. The context-size tip tells the agent how to call it in conversational use (subset sections, channels filter, max_grid_points).

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

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

The description goes far beyond the annotations (which already declare readOnly, idempotent, etc.) by explaining subtle behaviors: fit_liveness heartbeat semantics, stall_threshold meaning, that stall_threshold_exceeded does not change status, and how to handle missing liveness data. This level of detail is exceptional and eliminates ambiguity.

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 structured with a clear purpose statement, then details on return values, liveness behavior, and polling guidance. Every sentence adds value; there is no filler. The critical information is front-loaded, and the parameter explanation is appended logically. It is concise for the complexity it covers.

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

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

Given the tool's complexity (liveness, stall thresholds, edge cases) and that an output schema exists (so return format is covered elsewhere), the description is fully complete. It addresses all possible scenarios an agent might encounter: supported vs unsupported backend, absent liveness, stall threshold semantics, and appropriate polling behavior. 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 0%, so the description must fully explain the parameter. It does: 'model_hash: The model hash returned by create_model or list_models.' This adds clear meaning about where to obtain the value, which is essential for correct usage. The description fully compensates for the lack of schema documentation.

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

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

The description clearly states the tool's purpose: 'Check the fitting progress of a model.' It specifies the resource (model) and the action (check status). It also distinguishes itself from sibling tools like get_model_results or get_optimizer_results by focusing on fitting progress, not results. The description is explicit and unambiguous.

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

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

The description provides clear usage context: it's for polling fitting progress, and explicitly instructs to 'Continue polling with backoff; do not automatically restart a fit.' It also warns about how to interpret liveness data and when not to infer health. While it doesn't name specific alternative tools, the guidance on when to use and what to avoid is sufficient for an agent to decide correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: the overwrite semantics of the latest run, the distinction between decision-math and fitted-convention columns, the stripping of all-None placeholder arrays, and the warning that ObjectiveMarginal and MroiAtOptimized are different quantities. This goes far beyond what annotations provide.

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

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

The description is long but every section earns its place: the two-mode distinction, the column-convention warning, and the parameter explanations are all necessary for correct use. It is front-loaded with the core purpose and mode distinction, then details. Slightly dense, but not bloated.

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

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

Given the tool's complexity — two modes, multiple result conventions, and a rich output schema — the description is remarkably complete. It explains the top-level keys for both modes, warns about column incompatibility, and clarifies which quantity answers which question. The output schema exists, so return-value details are not the description's job, and the description still adds the interpretive context the schema cannot.

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 0%, so the description must carry the parameter meaning. It does: model_hash is 'Hash of the model that was optimized,' and run_id is 'Optional optimization run id from run_optimizer's response' with guidance to pass it to poll a specific run. The description could add a bit more about the format of model_hash, but it fully compensates for the schema gap.

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

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

The description states a specific verb ('Get') and resource ('budget optimization status and results'), and immediately distinguishes two modes: without run_id returns model-level state, with run_id returns a specific run. This clearly differentiates it from siblings like run_optimizer, get_model_results, and get_scenario_results.

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

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

The description explicitly tells the agent when to use each form: poll without run_id for the latest model-level state, and pass run_id to poll a specific run's completion. It also warns that a newer run overwrites the latest state, so a poller can lose sight of its own run — a clear when-not-to-use signal.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds genuinely new behavioral context: the create:models scope requirement, the meaning of each status value, and actionable error_code semantics (re-start on interrupted/not_started, error names the failing source/transform). This is far beyond what structured fields convey.

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

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

Front-loaded with the returned shape, then next-step routing, error semantics, and scope. Dense but each clause earns its place; slightly packed with parenthetical enumerations.

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

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

Given an output schema exists, the description needn't explain return values but does so helpfully, and it adds scope and error handling. The remaining gap is the undocumented parameter formats, which leaves the 0%-coverage schema slightly under-supported.

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 0%, so the description carries the burden for pipeline_ref and run_id, but it never defines pipeline_ref's format (id vs slug) or where to obtain it. It only obliquely references run_id via the returned-object notation, so it partially but not fully compensates.

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 one run of an owned pipeline') and enumerates the returned fields, so the agent knows exactly what it retrieves. It does not explicitly differentiate itself from nearby siblings such as list_pipelines or list_pipeline_versions, leaving that gap to the reader.

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

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

Gives clear workflow context: poll scheduled runs the same way, and on success route version_id into get_recipe_draft_template. It stops short of stating when to prefer this over alternatives like list_runs or list_pipeline_versions, so there are no explicit exclusions.

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

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

Annotations already provide readOnlyHint and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond that: the meaning of content_hash vs rules_hash, the nullability of derived_from name/hash when the source has been deleted, and the fact that 'nothing is written.' This helps the agent understand side effects and edge cases.

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 a single dense run-on sentence packed with field lists and parentheticals. It is front-loaded with the core purpose, and every piece adds information, but the lack of punctuation breaks makes it harder to parse. It is appropriately sized for the complexity but could be structured better with separate sentences or bullet-like breaks.

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

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

The tool has an output schema, so return format is covered structurally. The description enriches context by explaining hash semantics, derived_from edge cases, and checks_summary composition. It includes the access note ('Shared viewers can read') and explicitly asserts no writes. For a read-only fetch with two params, this is quite complete, though it omits error behavior for missing policies.

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 0%, so the description must compensate for parameter meaning. It does not. It never explains study_id or policy_id, nor whether policy_id is globally unique or scoped to the study. The only clue is the tool name and schema titles, which are generic. This is a significant gap for a tool with two required parameters.

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

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

The description opens with a specific verb and resource: 'Read one immutable policy in full' and enumerates the exact fields returned, including hashes and usage references. It differentiates from siblings like list_quality_policies (listing) and diff_quality_policies (comparing) through its focus on a single policy's full detail.

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 this is the detailed single-policy reader but never explicitly contrasts it with alternatives. The only sibling mention is 'see diff_quality_policies' in the context of the derived_from field, which is a cross-reference, not a when-to-use guide. There is no statement like 'for a list, use list_quality_policies' or 'for comparisons, use diff_quality_policies'.

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 read-only, idempotent, open-world, and non-destructive behavior, so the bar is lower. The description adds useful context: the response is a complete snapshot with a concurrency version, edits should preserve all fields, and the draft is not an executable recipe.

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, each adding distinct information: action, editing directive, and state warning. It is front-loaded with the core read operation and contains 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?

Given a single obvious parameter, an output schema, and rich annotations, the definition covers the important non-obvious semantics: completeness, concurrency, and draft validity. It could go further by explaining how the concurrency version should be used when updating, but this is not essential for a read tool.

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

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

The input schema has no property description and the tool description never mentions draft_id, so it doesn't compensate for 0% schema description coverage. The parameter name is self-explanatory, but the description adds no meaning about how to obtain or format the ID.

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

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

The first sentence uses a clear verb ('Read') with a specific resource ('complete authoring snapshot and concurrency version'), going well beyond the tool's title. It also distinguishes the draft-read operation from siblings like get_recipe_draft_template or publish_recipe_draft by emphasizing completeness and draft state.

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

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

The instruction 'Preserve all fields when editing' provides real guidance for a read-then-edit workflow, and the warning that drafts are unvalidated authoring data sets expectations. However, it never names sibling tools or explicitly states when to choose get_recipe_draft over get_recipe_draft_template, get_recipe_revision_authoring, or list_recipe_drafts.

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 mark the tool read-only, idempotent, and non-destructive. The description adds non-obvious behavior: defaults are not a validated model, retrieved data is frozen with verified lineage, and the preview is editable. No contradiction with annotations.

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

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

Three sentences, front-loaded with the core deliverable, then parameter options, then caveats. No filler or repetition of schema titles.

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

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

Output schema exists, so return format needs no explanation. Combined with schema, the description covers the deliverable, parameter sourcing, constraints, downstream workflow, and non-mutating behavior sufficiently for an agent to call it correctly.

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

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

Schema descriptions are 0% so the description must carry parameter meaning. It meaningfully explains uploaded_file_id and pipeline_version_id by naming their source tools and exclusivity, but family is left to its enum values with no explanation.

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?

Uses a specific verb ('get') and names the resource: shared wizard defaults, hash, and envelope schema. Also states what it is not ('Does not create, publish or run anything'), separating it from create_recipe_draft and publish_recipe_draft.

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 sourcing instructions: uploaded_file_id comes from list_uploads and pipeline_version_id from list_pipelines/list_pipeline_versions, with an explicit 'never both' constraint. It describes downstream use (copy snapshot into create_recipe_draft) but does not explicitly route to a sibling like get_recipe_draft when a saved draft is needed.

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/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: immutability of the revision, that engine.state current/stale predicts whether launch will be refused, and that lineage availability is checked live with true/false/null meanings. It is let down only by being heavily oriented toward return-value semantics the output schema already carries.

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

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

The most important statement is front-loaded, and individual sentences do carry information rather than filler. However, the body is a dense, jargon-heavy wall of text with nested parentheticals and quoted example strings that makes it hard to parse for an agent scanning for the operative facts.

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 an output schema, explaining return fields is largely redundant, and the description nonetheless spends most of its length there. It is fairly complete on what the response means but omits the arguments entirely, which is the more important gap for correct invocation.

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

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

Schema description coverage is 0% and neither of the two required parameters (recipe_id, number) is mentioned anywhere in the description. 'Read one immutable revision' hints that some identifier designates the revision, but the description adds essentially no meaning about what these arguments are or their format.

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

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

The opening sentence states a specific verb and resource: 'Read one immutable revision with its inspection block.' That clearly distinguishes it from mutating siblings, but the description never differentiates it from close siblings such as get_recipe_revision_authoring or diff_recipe_revisions, leaving the agent to infer which revision-reading tool to pick.

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

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

Usage is implied rather than stated — it is the tool for inspecting a single stored revision. The description does give actionable interpretation guidance ('treat them as stored-but-unused and do not "fix" them by editing unless the gating setting changes too'), but there is no explicit when-to-use/when-not or routing to alternatives.

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

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

Beyond the annotations (which already declare read-only, idempotent, non-destructive), the description discloses a specific error contract (404 for api_mmm/model_snapshot/legacy), the exact fallback semantics when dataset bytes no longer hash to the fitted origin (source is null, source_available false, reason), and the reassuring guarantee that 'the published revision stays unchanged' and it 'does not create or fit anything'.

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

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

Four dense sentences that are front-loaded with the core purpose, followed by return semantics, the dataset-hash caveat, and downstream usage. Every sentence earns its place, though it runs long enough that the parameter meaning never gets a sentence.

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?

An output schema exists, so the description needn't enumerate return fields — yet it explains the non-obvious one (source_available / source_unavailable_reason) rather than just listing names. Combined with the error and downstream-usage context, the definition is complete except for the unexplained 'number' parameter.

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 0% and the description adds no meaning for either parameter. 'recipe_id' is self-evident from the name, but 'number' is ambiguous (revision number vs ordinal) and is never explained; the description only mentions revision_id as a return field, not as input semantics. With 0% coverage the description should have compensated and does not.

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 ('Read the authoring snapshot behind a published revision') and immediately narrows scope by enumerating which revision kinds (authoring_draft, wizard, base_model) carry a snapshot and which (api_mmm, model_snapshot, legacy) do not. This distinguishes it cleanly from the sibling get_recipe_revision and get_recipe_draft.

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

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

Gives explicit conditions for success (three revision kinds) and failure (404 for the others), and routes the agent onward to create_recipe_draft with the correct argument ('target for an in-place edit, source_revision_id for a branch'). It does not explicitly compare against the sibling get_recipe_revision, so a small inference remains, but the when-to-use context is otherwise clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds meaningful behavioral context beyond these: a newer run overwrites the latest scenario, and failed scenarios return an HTTP 200 with status 'failed' plus an error message in the body, so callers must check the status field.

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

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

The description is lengthy but earns its length: mode-by-mode behavior, a critical failure-mode note, and an Args block. The core distinction between the two forms is front-loaded, and every section adds necessary information with no filler.

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

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

An output schema exists, so detailed return-value documentation is unnecessary. For a two-mode polling tool, the description covers overwrite semantics, failure representation, run_id provenance, and when to use each form, leaving no practical gap for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains model_hash as the hash of the model the scenario was run on, and defines run_id's format ('scn_...') plus where to obtain it: from run_scenario's response or list_runs(artifact='scenario'). This fully covers both parameters.

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 pairing ('Get scenario prediction results') and then defines two distinct behaviors: model-level latest state versus a specific saved run identified by run_id. This clearly distinguishes it from run_scenario and list_runs, which are the most related 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?

The description explicitly states the condition for each invocation form: without run_id returns the latest scenario state with overwrite risk, while with run_id fetches a specific saved run. It also says directly, 'Poll THIS form when you need to know whether your own run completed, or to disambiguate back-to-back scenarios,' which is unambiguous usage guidance.

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

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

The description goes beyond the readOnlyHint and idempotentHint annotations by warning that template data may contain NaN/null values that must be replaced with 0 or the prediction will fail. It also discloses the presence of operating_margin, variable_transforms, and periodicity, adding behavioral context not available from annotations alone.

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

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

The description is longer than average but well organized: a purpose sentence, response contents, an IMPORTANT block, a warning, and an Args section. There is minor redundancy between the initial response summary and the later IMPORTANT enumeration, but each section adds useful information and the critical usage directive 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 2-parameter tool with an output schema, this description covers prerequisites (completed model hash), intended call order, return fields, NaN handling, and parameter defaults. Nothing critical for invoking the tool 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?

With schema description coverage at 0%, the description compensates by defining model_hash as 'Hash of a completed model' and periods_forward as the number of future periods to generate with a default of 12. This adds some meaning beyond the bare schema types, though the model_hash explanation remains somewhat terse.

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 action — 'Generate a forward-period scenario template from a completed model' — and immediately differentiates itself from sibling execution tools by naming run_scenario and run_optimizer. The description also itemizes the template's contents, so an agent understands exactly what resource is produced.

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 an explicit directive: 'IMPORTANT: Always call this before run_scenario or run_optimizer to discover...' This clearly states when to use the tool. It also enumerates what information to extract (channel names, average CPM, baseline rows, classification) and warns about downstream failure, which is strong pragmatic 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 cover read-only, idempotent, open-world, and non-destructive behaviors. The description adds value by explaining that question and context fields are descriptive intent, not enforced instructions, and that a concurrency version is included. This goes beyond annotations but does not discuss authentication, rate limits, or other behavioral traits.

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 highly concise at two sentences, front-loading the core action ('Read a study') followed by a useful clarification. No wasted words; every sentence earns its place.

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

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

With an output schema present and low complexity (single parameter), the description covers the primary purpose and a nuance. However, it lacks usage guidance and does not specify what the optimistic concurrency version is used for, leaving some gaps in agent comprehension.

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 0%, and the description does not explicitly explain the study_id parameter, though it is implied by 'read a study'. Since the parameter is a simple ID, this is a minor gap, but the description should compensate given the low coverage according to the guidelines.

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 'Read a study' with a specific verb and resource, and adds the detail of returning the optimistic concurrency version. However, it does not explicitly differentiate from sibling tools like get_study_overview or list_studies, though the focus on reading a single study with a concurrency version implies distinction.

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 offers no guidance on when to use this tool versus alternatives. It does not mention contexts where this should be preferred over get_study_overview or list_studies, nor does it state any exclusions or prerequisites.

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

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

Annotations already mark this as readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral nuance: stale champion handling, holdout-use blocking, validation resolution effects, reviewer-declared references, and the frontend-session limitation. It enriches the agent's understanding of data semantics beyond the annotations without contradicting 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 dense but not bloated. It front-loads the core purpose in the first sentence, then layers important caveats and constraints. Each sentence adds information relevant to correct invocation or interpretation. It is appropriately concise for the amount of behavioral detail it conveys.

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?

An output schema exists, so return-value documentation is not required. The description covers the key data aspects (incumbent, blockers, candidates, history) and important edge cases (stale champions, holdout blocking, validation resolutions, session limitations). It is complete enough for an agent to understand what this tool returns and the conditions that affect its results.

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

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

The schema has 0% description coverage, so the tool description must compensate. It does not mention study_id at all, leaving the agent to infer its meaning from the parameter name. For a read tool with a single obvious parameter, the lack of explicit explanation is a minor gap, but given the low coverage, the description fails to add any value beyond the schema.

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

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

The description opens with a clear verb and resource: 'Read incumbent, eligibility blockers, accepted candidates and immutable champion history.' This precisely states what the tool returns and distinguishes it from other study-related tools like get_study or get_study_run by focusing on the champion concept. 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?

The description provides behavioral context (e.g., 'Ordinary viewing does not block', 'Selection/replacement/revocation require an owner frontend session') that implies this is a read-only query tool. However, it never explicitly names alternative tools or states when to prefer this over a sibling like get_study. Usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations: it is a lightweight 'identity and counts only' call that deliberately excludes frozen configuration and reports, and it returns the latest revision/run/decision rather than full history. This helps an agent predict cost and scope of the call.

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 dense but well-organized: it front-loads the purpose, lists the included content in a compact series, states exclusions, and ends with a clear next-step routing. Every sentence earns its place, and the length is appropriate for the amount of useful routing 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?

The tool has a single required parameter, a rich output schema, and safety annotations. The description covers what the call returns, what it deliberately omits, and how to follow up. There is no missing information an agent needs to decide whether to call this tool or to interpret its scope.

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 0%, so the description must compensate for the single study_id parameter. It does so implicitly by stating the tool reads 'a whole study' and by naming the study-related entities returned. However, it does not explicitly state that study_id is the identifier to pass, nor does it give format guidance. With only one obvious parameter, the baseline is high, and the description is mostly adequate.

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

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

The description opens with a clear verb and resource: 'Read a whole study at a glance in one small call' and then enumerates exactly what is included (study, budget, recipes with latest revisions, run counts, active policies, champion summary, last decision). It also explicitly states what is NOT included ('no frozen configuration or reports'), which distinguishes it from heavier study-reading tools like get_study or list_study_recipes.

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

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

The description gives explicit usage guidance: 'Call this first, then expand exactly the recipe, run or assessment you need' and names the specific sibling tools to use next (list_study_recipes with expand, get_recipe_revision, list_study_evaluations with expand). This is a clear when-to-use and what-to-use-instead directive.

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

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

The description goes well beyond the annotations. It discloses that the read does not expose predictions or add events, that listing assessments never records, that histories before jellyfish #837 may contain extra rows, and that nothing is deleted because holdout-use declarations reference event ids. These are critical behavioral traits not captured by readOnlyHint/openWorldHint/idempotentHint/destructiveHint. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose and return fields, then adds necessary caveats about event recording, historical anomalies, and limitations. It is longer than average, but the complexity of the tool justifies the length. Slight redundancy in the caveats could be trimmed, but overall it is well-structured.

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

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

Given the tool's complexity, the single parameter, the rich annotations, and the presence of an output schema, the description is complete. It explains what is returned, what is not covered, how events are recorded, and the implications for holdout status. An agent has everything needed to decide when to call this tool and how to interpret its results.

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 0%, so the description must compensate for the single parameter run_id. The description repeatedly references 'this run' and 'matching recorded dataset/windows in this study', implying run_id identifies the run, but it does not explicitly state that run_id is the run identifier or explain its format. However, with only one parameter and the title 'Run Id' in the schema, the meaning is largely inferable. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Read') and resource ('partial prediction-access history for this run and matching recorded dataset/windows in this study'), and enumerates the exact fields returned. It clearly distinguishes itself from sibling tools by focusing on prediction-access history rather than study metadata, runs, or models.

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

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

The description explicitly explains when this tool is appropriate: to read prediction-access history for a run and its recorded dataset/windows. It also provides exclusions ('Earlier activity, other result routes and offline work are not covered; absence never proves untouched holdout status. Repeated access does not prove retuning.'), which tells an agent when NOT to rely on this tool. This is strong usage guidance.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds that the tool returns durable status and the linked model, which is useful context, but it does not clarify what 'durable' means or describe other behavioral constraints.

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 a single focused sentence with no filler. The core action and key output are front-loaded, making it easy for an agent to parse quickly.

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 one-parameter read tool with strong annotations and an output schema, this is nearly complete. The only slight gap is the ambiguity of 'durable' and the lack of any link to the broader study context, but the agent has enough to call it correctly.

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

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

The schema has one parameter, run_id, with 0% description coverage, and the tool description does not compensate by explaining the parameter's meaning, format, or source. The property name is self-evident, but the description adds no value beyond the schema.

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

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

The description names a specific verb ('Read') with a clear object ('durable run status') and a distinct output ('the linked model'). This differentiates it from sibling getters like get_model_status or list_study_runs.

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

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

No guidance is given about when to use this tool versus alternatives. The sibling list includes several related read tools, but the description does not name them or state any exclusions.

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