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

With no annotations, the description carries the full burden. It does disclose the effective side effect ('marking it as desired to be served') and that it avoids a new revision, plus the return shape, but is silent on permissions/authorization, idempotency, and reversibility for what is a mutation.

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 and usage are front-loaded in the first two sentences. The remainder is repetitive object-store boilerplate ('The output is automatically stored...', 'Use the returned object ID...') that restates the same idea multiple times and dilutes the signal.

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?

It covers purpose, usage, and return handling, but with no annotations and no output schema it should do more: it omits auth requirements and, importantly, fails to disambiguate from the sibling 'activate_deployment_revision', which is the biggest risk for this 1-param mutation 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%, so the description must compensate for the single required parameter. ':param deployment_id: ID of the deployment.' merely restates the schema title ('Deployment Id') and adds no format, identifier source, or lookup guidance.

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 ('Re-activates a deployment's current active revision') and even scopes it as the current active revision without pushing a new one. However, it never acknowledges or distinguishes itself from the near-identical sibling 'activate_deployment_revision', which an agent selecting between the two would need.

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

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

Explicitly states when to use it: 'to bring a deactivated deployment back online without pushing a new revision', which contrasts with a revision-pushing flow. No explicit when-not or named alternatives (e.g., deactivate_deployment, update_deployment) are offered, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses the return path (object ID like @obj_123 and object-store interaction), but for a mutation it omits key traits: whether activating replaces the currently served revision, required permissions, and reversibility/downtime implications.

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 is front-loaded and the docstring params are compact, but the trailing block about the object store is repetitive ('object ID' repeated across three sentences) and bloats the definition with shared boilerplate.

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-param mutation with no annotations and no output schema, the definition covers the return/object-store behavior but leaves important gaps: effect on the currently served revision, auth requirements, and failure semantics. Adequate but incomplete.

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 is the only source of parameter meaning. It identifies both params ('ID of the deployment', 'ID of the revision to activate'), but these are near-tautological restatements of the names and add no format, constraint, or lookup detail.

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

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

States a specific verb (activates) and resource (revision) plus a concrete effect: 'marking it as the deployment's desired served revision.' This distinguishes it from the sibling activate_deployment (which targets a deployment, not a revision), though no sibling is named explicitly.

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

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

There is no when-to-use guidance, no prerequisites, and no reference to alternatives such as activate_deployment or create_deployment_revision. The agent must infer the calling context 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?

With no annotations, the description carries the behavioral disclosure burden. It usefully states the maximum tag count (three), the tag_name validation rules, and the return shape ('full tag list after the add, or error message'). However, it omits permissions/auth requirements, idempotency behavior for duplicate tags, and reversibility.

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 content is front-loaded reasonably well: purpose, limit, parameter notes, and return value. However, the trailing paragraphs about automatic object storage, preview object IDs, and object store tools are generic boilerplate that does not clearly earn its place for a simple tag-adding tool and adds noise.

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 mutation tool with no annotations or output schema, the description is fairly complete: it states what the tool does, the input constraints, the return value, and a deployment-level limit. It still lacks auth, error-condition, and duplicate-tag behavior, but covers the essentials an agent needs to call 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 must compensate, and it largely does. It explains that deployment_id is the ID of the deployment and gives concrete character and length constraints for tag_name. It could go further by indicating where deployment_id comes from, but it meaningfully documents 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 first sentence states a specific verb and resource: 'Adds a tag to a deployment.' It distinguishes the action from sibling tools like delete_deployment_tag and list_deployment_tags implicitly through the verb 'Adds.' However, it does not explicitly name or contrast against those siblings, so it falls just short of a 5.

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

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

The description offers no when-to-use guidance, no alternatives, and no exclusions. The hard constraint of at most three tags is useful context but is a limitation, not usage direction. An agent is left to infer that this tool should be used whenever a tag needs to be added.

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?

No annotations exist, so the description carries the full load. It does disclose genuinely useful behavior an agent could not otherwise know: nothing is replayed, nothing is billed, and a Session the Dataset already holds is silently skipped rather than duplicated. It does not address permissions, whether duplicates in the input list are also skipped, or what the 'error message' return means for partial adds.

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

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

The opening two sentences front-load the action and the cost/side-effect profile, which is exactly what an agent needs first. The trailing Sphinx-style :param/:returns block partially duplicates the nested schema descriptions, keeping it short of ideal, but nothing is padded or off-topic.

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

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

For a mutation tool with no annotations and no output schema, the description covers the behavior profile, the input-shape constraint, the conditional parameter, and the return value ('The Dataset with all its test cases, or an error message'). Only the failure/partial-success conduct and permission requirements are left implicit, which is a minor gap at this complexity.

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?

Top-level schema coverage is reported as 0%, and the description supplies the missing meaning: test_cases are appended in order, and pipeline_name is conditionally required only when a test case carries a session_id. That conditional dependency, plus the mutual exclusivity of session_id/inputs, is real semantics the top-level schema does not express.

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

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

States a specific verb and resource with scope: 'Adds test cases to the end of a Dataset', plus a distinguishing clause that it 'Replays nothing and costs nothing', which separates it from replay_session. It also names the sibling copy_test_cases as the route for cross-Dataset reuse, so an agent can pick this tool 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?

Gives an explicit alternative ('To reuse test cases from another Dataset use copy_test_cases') and an explicit exclusion rule (a test case is session_id or inputs, never both; pipeline_name is required when session_id is used). What it lacks is routing against the adjacent mutation siblings like update_test_case or remove_test_cases, which an agent must infer.

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

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

With no annotations, the description carries the full burden and does well: it explains that the copy preserves Session/inputs, name, expected data and scripts, that each copy receives a new id so editing the copy leaves the original untouched, and that cases are appended to the end of the target dataset. It omits any mention of permissions, quota/limits, or duplicate handling, which keeps it short of 5.

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

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

Front-loaded with the core action and scope, then behavioral detail, then the param/return block. The Sphinx-style ':param:' lines are mildly redundant with the prose but every sentence adds 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?

Two required params, no output schema, no annotations – and the description supplies the mutation semantics, id-generation/independence guarantee, append behavior, an id-discovery pointer, and the return value ('The Dataset with all its test cases, or an error message'). Only missing pieces are failure conditions and permission requirements.

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, and it does: dataset_id is defined as the target ('The Dataset to copy into') and test_case_ids as an ordered list ('in order'), which conveys the ordering semantics absent from the schema. It does not clarify that ids may come from any other dataset's cases, a minor residual 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?

States a specific verb and resource ('Copies test cases') plus the directional scope ('from any Dataset of the workspace to the end of this one'), which implicitly separates it from add_test_cases / remove_test_cases. It does not name a sibling explicitly, so it falls short of the 5 bar.

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 one concrete prerequisite – 'Find ids with ``get_dataset``' – which is genuinely useful. However it never says when to prefer this over add_test_cases (which presumably creates new cases in place) or remove_test_cases, so the choice among siblings is left to inference.

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

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

No annotations are supplied, so the description carries the full burden and does well: 'Replays nothing and costs nothing' rules out execution side effects and billing, and 'A Session sent twice becomes one test case' discloses dedup behavior. Gaps remain around name uniqueness/validation and what happens on partial failure, but the core behavioral profile is 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?

Front-loaded with the action and cost/replay disclaimer, then the input rules, then next steps — a good order. The trailing ':param name:'/' :param test_cases:' lines restate what the prose already conveyed, which is mild duplication but not damaging.

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, non-annotated mutation tool with no output schema, the description covers what is created, the exclusivity rule, dedup behavior, cost, the return value, and the follow-up call. Only edge cases (name collisions, validation errors) are unaddressed.

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

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

Top-level schema coverage is 0% (no descriptions on name/test_cases/pipeline_name), so the description must compensate, and it does: it defines name, states pipeline_name is required when a test case carries a session_id, and defaults test_cases to none. It also clarifies the session_id-vs-inputs exclusivity and expected semantics that the schema only partially documents in $defs.

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 plus scope: 'Creates a Dataset, optionally with its first test cases.' It also implicitly separates itself from siblings by pointing to add_test_cases for later additions and create_experiment for running, so an agent can distinguish it from update_dataset/get_dataset/add_test_cases without opening a schema.

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

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

Explicitly routes the agent: find Sessions with list_sessions, use add_test_cases to extend an existing Dataset, and create_experiment with the returned dataset_id to run it. It also states the mutually exclusive input rule (session_id or inputs, never both), which is the main selection decision the agent has to make.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses default behavior (sizing defaults to DEVELOPMENT unless explicit sizing fields are given), the post-creation state (no active revision without a pipeline), and that output is auto-stored and returned as an object ID. It says nothing about permissions/auth requirements, provisioning side effects, or costs, which are meaningful gaps for a create-a-resource operation.

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 and the critical 'no active revision' caveat are front-loaded, and the param reference is justified by 15 undocumented params. However, the Examples block is generic boilerplate that references 'data' and 'threshold' – parameters that do not exist on create_deployment – which adds noise and potential confusion rather than value.

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 15-parameter mutation tool with no annotations and no output schema, the description is fairly complete: it covers parameter meaning, defaults, the revision workflow dependency, and the return/preview behavior (object ID usable with object store tools). It omits auth/permission prerequisites and any description of the created deployment's fields, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: a full :param list documents all 15 parameters with semantics and defaults (e.g., idle_timeout_in_seconds as 'Seconds of inactivity before scaling down', the MANAGED/SERVERLESS and PRODUCTION/DEVELOPMENT/CUSTOM enums, and the @obj_id reference syntax). Some entries are near-tautological (e.g., 'Name of the deployment', 'Maximum number of index replicas'), keeping it out of the top score.

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 gives a specific verb and resource ('Creates a new deployment (AI Gateway)') plus the scoping condition that it is optionally linked to a pipeline. An agent can distinguish this from siblings like create_deployment_revision, update_deployment, and deploy_pipeline. It stops short of explicitly naming which sibling to use in which situation.

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

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

The description explains the key branch: without an origin_pipeline_id the deployment has no active revision until create_deployment_revision and activate_deployment_revision are called, which effectively routes the agent to the follow-up tools. It lacks explicit exclusions or guidance on when not to use create_deployment, but the workflow context is clear.

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

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

With no annotations, the description carries the burden and does well: it discloses that creation is non-serving and requires a separate activation step, and explains that the result is auto-stored and returned as a preview with an object ID. It omits permission/auth requirements, reversibility, and error conditions beyond a generic "or error message".

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 parameter notes are front-loaded and useful, but the description is padded with leaked Sphinx directives and a generic template block whose examples use parameters that do not exist on this tool (data, threshold). Those examples are actively misleading and do not earn their place.

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

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

For a 5-param mutation tool with no annotations and no output schema, the description covers purpose, the activation prerequisite, per-parameter meaning, the object-reference convention, and the return shape. Missing pieces are edge behavior such as auth requirements and validation 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 0%, so the description must compensate, and it documents all five parameters including the source_type enum values and the situational role of config_yaml vs source_version_id. It also explains the @obj_id / @obj_id.path.to.value reference syntax, which the schema never mentions.

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 ("Pushes a new revision onto a deployment") and immediately scopes it against the sibling that serves revisions. An agent can distinguish it from activate_deployment_revision without opening the schema.

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

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

Explicitly names the follow-up tool and the condition that selects it: creating a revision does not serve it, call activate_deployment_revision to serve it. No exclusions are given for when *not* to create a revision, so it stops short of a full when/when-not/alternatives statement.

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

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

With no annotations provided, the description carries the whole burden and does it well: it warns that Judged Metrics cost money when run, that hub-api rejects code whose @metrics declaration cannot be parsed, that the name must be unused in the workspace, that the Evaluator scores nothing until a Metric Group runs it, and that new_metric_group_name creates an additional object as a side effect.

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?

Behavioral warnings and prerequisites are front-loaded in the first sentences, which is good structure. It loses a point because the trailing :param/:returns block partially restates what the prose already explained (notably python_code and the Metric Group options), adding length without new 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 creation tool with a 4-parameter schema, no annotations, and no output schema, the description covers prerequisites, side effects, failure modes, cost implications, and even the return value ('The created Evaluator, or an error message'). Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 0% (bare titles only), yet the description documents all four parameters with meaning beyond the schema: name must not already exist, python_code is the Evaluation Function whose @metrics declaration is mandatory, metric_group_ids are existing groups with insertion at the end of each set, and new_metric_group_name creates a group containing only this Evaluator. This fully compensates 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?

Opens with a specific verb+resource and scope: 'Creates an Evaluator from Python source and adds it to the workspace.' It then names the sibling tools it is not (try_evaluator for validation, list_evaluator_templates for scaffolding, update_evaluator for changes), so an agent can distinguish it 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?

Gives explicit when-to-use routing: validate first with try_evaluator, start from list_evaluator_templates rather than from scratch, and use update_evaluator for later changes. It also explains the two mutually available paths for grouping (metric_group_ids vs new_metric_group_name) and the later alternative (update_metric_group).

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 no annotations, the description carries the full burden and does: it discloses that creating costs money (pipeline replays on customer models plus billed LLM evaluators), what preview returns (reused_sessions, replays_needed, cells vs max_cells), and that preview starts nothing. It also explains the side effects of reuse_sessions=False and that a Recorded baseline reuses existing Sessions with nothing replayed.

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 cost warning and the preview-first rule, which is the most important thing an agent must know. It is long but dense; the only waste is that preview, reuse_sessions, and sessions_per_test_case are each explained twice, once in prose and again in the parameter list.

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 everything needed for an 11-parameter, high-cost mutation with no annotations: cost model, preview protocol, baseline pairing rules, session reuse semantics, and a :returns: line standing in for the absent output schema. Nothing material is missing.

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

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

Schema coverage is 0%, so the description must supply meaning, and the :param: block does — baseline_pipeline_name/version_id must be given together or omitted for a Recorded baseline, sessions_per_test_case is 1..50 default 1, replay_mode enum values are interpreted, reuse_sessions and preview defaults are stated. A few entries (name, dataset_id) merely restate the parameter, keeping it short of a 5.

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 — creates an Experiment comparing a candidate pipeline version against a baseline — and immediately explains the two sides, the dataset/metric-group scoping, and the two baseline flavors. An agent can distinguish it from get_experiment, list_experiments, and start_experiment_run without opening any schema.

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

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

Explicit workflow guidance: call first with preview=True, show the plan to the user and get a yes before creating for real. It also routes id discovery to list_metric_groups and list_experiments, and points to get_experiment_results / get_experiment for reading and following the run.

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

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

No annotations exist, so the description carries the full burden. It does disclose useful behavior: the return is 'a message and the created index, or an error message', the output is auto-stored, and an object ID is returned for chaining. It says nothing about permissions, uniqueness enforcement on index_name, or side effects, which leaves real gaps for a mutation 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?

The purpose is front-loaded, but the body is bloated with Sphinx docstring artifacts (:param:, :returns:), generic boilerplate about the object store repeated twice, and example calls whose parameter names (data, threshold) do not match this tool's schema. Much of the text does not earn its place.

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

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

With no output schema and no annotations, the description does cover the return shape and object-store mechanics, which is the minimum needed to use the result. It omits duplicate-name behavior, required permissions, and what the YAML configuration must contain, so an agent could still call it incorrectly.

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 names all three parameters and adds genuinely useful object-reference syntax ('@obj_id.path.to.value') not present in the schema, but the per-parameter notes are thin (yaml_configuration is not explained beyond 'YAML configuration to use') and the code examples reference non-existent parameters (data, threshold), which is actively misleading.

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 gives a specific verb+resource ('Creates a new index') scoped to the Haystack Enterprise Platform workspace, which is enough to distinguish it from unrelated siblings like create_pipeline or create_deployment. It does not explicitly contrast itself with the closest siblings (update_index, validate_index, deploy_index), so it stops short of a 5.

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

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

There is no guidance on when to use create_index versus update_index, validate_index, or deploy_index, nor any stated prerequisites. The only routing advice concerns post-call object handling ('use the object store tools'), not tool selection.

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 no annotations supplied, the description carries the full load and does so well: it discloses cost implications, that evaluators are referenced by name rather than version so each run uses the newest version, the relative-normalization math for weights, the exact validation rules hub-api enforces (Normalized mean, no duplicate pairs), and the degraded `usable: false` / `unusable_reason` state that is retained but no longer counted. These are non-obvious failure and lifecycle behaviors an agent could not infer from the schema.

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

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

Front-loaded with the purpose before the caveats, and every paragraph maps to a decision the caller must make. It is dense and long-ish for a three-parameter tool, and the weight-normalization example is partly redundant with the schema's own wording, but nothing is 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?

A mutation tool with no annotations and no output schema, yet the description covers prerequisites, cost, validation rejection behavior, version-drift semantics, and even a returns line ('The created Metric Group, or an error message'). An agent has enough to call this correctly on the first try.

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% at the top level, so the description must compensate, and it does: `evaluator_ids` is not just a list but an ordered list controlling result display order with a minimum of one, and `weights` is explained structurally and semantically. The business rules that no duplicate evaluator/metric pair may appear and that weights divide by their sum add meaning well beyond the raw 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?

States a specific verb and resource and goes further by defining the resource: 'a named, ordered set of Evaluators to score Sessions of any pipeline with.' That is far more than a restatement of the name. It does not, however, explicitly route against the adjacent lifecycle siblings (update_metric_group, list_metric_groups, delete_metric_group), so it lands at clear-but-undifferentiated rather than fully distinguishing.

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 real context for when to reach for it and points to the prerequisite tool: 'Find Evaluator ids with list_evaluators.' It also warns that running the group costs money, which is a practical decision input. It stops short of explicit when-not guidance, e.g. when to update an existing group instead of creating a new one.

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 output is automatically stored with object ID and returns a preview, which is useful. However, no annotations are provided, and the description does not cover potential side effects or authorization needs.

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

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

Purpose front-loaded, but includes redundant docstring-style param/return lines and mismatched examples. Could be more concise and accurate.

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 no output schema, 0% schema coverage, and many siblings, the description omits crucial context like YAML structure, prerequisites, error handling, and differentiation from pipeline versioning tools.

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

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

Schema description coverage is 0%. Description adds minimal info (pipeline name and YAML config), but the examples are mismatched, referencing non-existent parameters 'data' and 'threshold', which confuses. No explanation of YAML 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?

Clearly states verb 'creates' and resource 'pipeline' within deepset workspace. Distinguishes from siblings like create_index or create_workspace.

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 examples and mentions object references for parameter passing, but lacks explicit guidance on when to use this tool versus alternatives like create_pipeline_version or deploy_pipeline.

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 immutability, version history, draft finalization, output storage, and object ID usage. No annotations, so description carries full burden and meets it thoroughly.

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

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

Well-structured with opening statement, behavior explanation, parameter list, and examples. Slightly verbose with redundant parameter docstring but not excessive.

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

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

Covers purpose, all parameters, behavior, output format, and usage examples. Adequate for a 4-parameter tool with no output schema.

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

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

Schema has 0% description coverage. Description compensates fully by describing each parameter, default values, reference format, and providing examples.

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

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

Clearly states it creates a new immutable version of an existing pipeline with YAML configuration. Distinguishes from siblings like create_pipeline and patch_pipeline_version.

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

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

Provides explicit usage context: "Use this to update a pipeline's configuration." Explains behavior with is_draft and object references, but lacks explicit exclusions or when-not-to-use.

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

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

No annotations provided, so the description carries full burden. It discloses mutation (creates), uniqueness requirement, output format with object ID, and storage behavior. However, it does not mention permissions, rate limits, or side effects.

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

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

The description is concise overall, but includes extra details about object store tools and referencing results, which are tangentially relevant. Could be slightly more streamlined.

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 simplicity (one parameter, no output schema, no annotations), the description covers purpose, input, output, and uniqueness constraint. Lacks error handling details and authentication requirements.

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 sole parameter 'name' has no schema description (0% coverage), but the description adds meaningful context: 'The name for the new workspace. Must be unique.' This compensates well 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 explicitly states 'Creates a new workspace with the specified name' and explains its role in organizing pipelines, indexes, and other resources. It clearly distinguishes from sibling tools like create_index and create_pipeline.

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 mentions the uniqueness constraint and that workspaces can be used after creation, but does not provide explicit guidance on when to use this tool versus alternatives or when not to use it.

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?

No annotations are provided, so the description carries full burden. It adds useful behavioral context by stating the active revision is preserved (implying reversibility), but omits permissions/auth requirements, whether served traffic is immediately stopped, and whether the action can be undone.

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 lead sentence is well front-loaded and earns its place, but the trailing object-store boilerplate ('Use the object store tools...', 'Use the returned object ID...') is generic and largely irrelevant to a deactivate operation.

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

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

For a one-param mutation with no output schema and no annotations, the description covers the return path reasonably well, explaining the object-ID preview and how to consume it, though the safety/permission profile remains undocumented.

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% and the single param is documented only as ':param deployment_id: ID of the deployment,' which restates the name. With one self-evident ID parameter the gap is minor, but the description adds no format or source detail to compensate.

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: 'Marks a deployment as no longer desired to be served, keeping its active revision intact.' The 'keeping its active revision intact' clause implicitly distinguishes it from delete_deployment, though it never names that sibling directly.

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

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

No explicit when-to-use guidance or alternatives. With siblings like delete_deployment, activate_deployment, and update_deployment in the list, the description never says when to prefer deactivation over deletion or how it relates to activation.

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 no annotations, the description fully carries behavioral disclosure: it explains resumable snapshot behavior, the always-returned inline run trace, state-modifying dry_run substitutions, and the resume rejection on dry_run mismatch. It also notes that outputs are auto-stored and can be referenced via object IDs.

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?

Although long, the description is well structured: a clear overview, mode breakdown, parameter definitions, and examples. Each section adds essential operational detail, and the first sentence front-loads the core purpose.

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

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

For a tool with 9 parameters, no annotations, and no output schema, the description is remarkably complete. It covers return shape, side effects, dry_run behavior, error visibility, object-reference usage, and example calls, leaving almost no operational ambiguity.

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 zero descriptions, but the description documents all 9 parameters, including mutual exclusions, defaults (break_at_visit_count=0), ignored inputs when resume_from is set, and the requirement that pipeline_version_id requires pipeline_id. This fully compensates for the schema 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 first sentence states a specific action and scope: 'Runs a pipeline configuration in debug mode: pin a breakpoint, resume a snapshot, or trace a full run.' It also explicitly distinguishes from saved pipelines ('directly (not a saved pipeline by name)'), which separates it from siblings like run_component or deploy_pipeline.

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 defines three mutually exclusive usage modes and tells users to pass YAML from get_pipeline_version/create_pipeline_version or a local draft. It provides concrete when-to-use guidance for dry_run ('Required for indexing pipelines... harmless for query pipelines') and warns to set it on resume too. However, it does not explicitly name alternative tools, so it stops short of full explicit exclusion 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 no annotations present, the description carries the full burden and does so well: irreversibility, cascading deletion of test cases, the fact that Experiments keep results but lose their link, a named refusal behavior with instruction to relay the message, and the downstream 409 consequences for change-sides and rerun-failed. This is exactly the side-effect detail an agent cannot get from the schema.

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

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

The consequence of deletion is front-loaded and every behavioral sentence earns its place. The trailing Sphinx-style ':param:' and ':returns:' fragments are documentation artifacts that mostly duplicate the schema and slightly dilute the otherwise tight prose.

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 no output schema, the description covers outcomes, failure modes, and cross-entity effects, and it states what is returned. What is missing is how to obtain a valid dataset_id and whether any permission/authorization conditions apply.

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

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

Schema description coverage is 0% and the only parameter line is ':param dataset_id: The Dataset's id.', which merely restates the schema title. It adds no format, sourcing (e.g. from list_datasets/get_dataset), or validity guidance beyond the property name.

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 plus the cascade scope: 'Deletes a Dataset and all its test cases.' That scope line alone separates it from siblings like delete_experiment or delete_deployment, and from non-destructive dataset tools such as remove_test_cases or update_dataset.

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

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

Gives a real precondition ('get a yes first') and describes when the call will fail (while something else still uses the Dataset). It does not route to an alternative for partial removal, e.g. remove_test_cases when only some cases should go, so the alternative-selection guidance is incomplete.

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

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

With no annotations, the description carries the full behavioral burden. It explicitly discloses the critical destructive trait ('along with all of its revisions. This cannot be undone.'), which is exactly what an agent needs. It could be improved by mentioning auth requirements or rate limits, but the core destructive behavior is well covered.

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 message is front-loaded and clear, but the description is bloated with 6+ sentences of boilerplate about object storage ('The output is automatically stored...', 'Use the object store tools...'), which is irrelevant to a destructive delete operation and dilutes the signal.

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 simplicity (1 required param, no output schema) and lack of annotations, the description covers the essential destructive warning but is incomplete on prerequisites and environment context. The included object-store boilerplate is noise for this operation.

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

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

Schema description coverage is 0% for the single parameter 'deployment_id', so the description must compensate. It does mention ':param deployment_id: ID of the deployment to delete.', providing a basic definition, but adds no format, syntax, or sourcing guidance beyond what the name implies.

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 ('Deletes') and resource ('deployment') and clarifies the cascading scope ('along with all of its revisions'). This distinguishes it from siblings like update_deployment or deactivate_deployment.

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

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

The description states it is irreversible but provides no guidance on when to use this tool versus alternatives like deactivate_deployment or delete_deployment_tag, nor any 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?

With no annotations, the description carries the full burden, and it does disclose one useful trait (case-insensitive tag matching) and the return shape. It omits important behaviors for a mutation: required permissions, idempotency (what happens if the tag is absent), and whether removal is reversible.

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, which is good, but the trailing block about automatic output storage, object IDs, and the object store is generic boilerplate that consumes roughly half the text without helping an agent call this delete tool.

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

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

For a two-parameter delete with no annotations and no output schema, the description covers purpose, both params, and the return value (full tag list or error message), which is adequate. It still leaves auth/permission requirements and failure modes unexplained.

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 compensate; it does document both params via the docstring (:param deployment_id:, :param tag_name:) and adds the case-insensitivity rule for tag_name. However, the descriptions are minimal paraphrases ('Tag to remove.') rather than adding format or constraint detail.

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

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

States a specific verb and resource ('Removes a tag from a deployment'), which is unambiguous. It does not explicitly distinguish itself from the close sibling add_deployment_tag or list_deployment_tags, but the verb makes the direction of the operation obvious.

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

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

No when-to-use guidance, no mention of the sibling add_deployment_tag/list_deployment_tags, and no prerequisites. The only guidance is the object-store boilerplate about passing the returned object ID to other functions, which covers follow-up usage rather than tool selection.

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 no annotations provided, the description carries the full burden and does it well: it declares irreversibility, explains exactly what is destroyed (the Experiment and its results), and explicitly what survives (sessions it reused, replays, scoring runs). It also states the return shape ("a confirmation, or an error message").

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 action and its immediate consequence, with no wasted sentences. The Sphinx-style ":param"/":returns:" markup reads as raw docstring artifacts rather than agent-facing prose, which slightly hurts readability.

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

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

Given zero annotations and no output schema, the description covers destruction scope, data retention, the confirmation requirement, and return shape — enough to call it safely. Missing pieces are permission/auth requirements, the id's provenance, and error conditions such as a nonexistent experiment.

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, but ":param experiment_id: The Experiment's id" only restates the parameter name. For a destructive one-parameter tool, it should say where the id comes from (e.g. list_experiments/get_experiment) or its format, since a wrong id is unrecoverable.

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 ("Deletes an Experiment and its results") and adds scope detail about what is and isn't removed. It is unambiguous against the many experiment siblings, but it never explicitly names an alternative or contrast tool, so it stops short of full sibling differentiation.

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?

"This cannot be undone: get a yes first" establishes a hard precondition (user confirmation) before calling, which shapes when the tool should be used. There is no routing guidance toward alternatives such as update_experiment or archiving, and no guidance on when deletion is unnecessary.

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 no annotations present, the description carries the entire burden and does so well: it declares the operation irreversible, discloses the cascading loss of scoring runs, notes that Evaluators survive, and warns that dependent Experiments lose side-changing and replay-rerun ability (409). That downstream consequence is information an agent could not infer from the schema or from any other sibling.

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 destructive warning and cascade scope are front-loaded in the first two sentences, which is the right ordering. It loses a point for retaining Sphinx docstring artifacts (":param", ":returns") and hard line breaks that add noise rather than information.

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

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

For a destructive single-parameter tool with no annotations and no output schema, the description covers reversibility, cascade behavior, retained entities, the referential-integrity failure mode, and what a success versus error response looks like. There is no material gap an agent would need filled before calling 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% and the only parameter text is ":param metric_group_id: The Metric Group's id," which essentially restates the property title. It does not say where to obtain the id (for example from list_metric_groups), so the schema gap is not really compensated, but with a single obvious required identifier the omission is minor.

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 and resource ("Deletes a Metric Group") plus the cascade scope ("together with all its scoring runs"), which is exactly the detail that separates it from update_metric_group and list_metric_groups in the sibling set.

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

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

Gives a concrete precondition — confirm with the user ("get a yes first") — and explains the blocking case where hub-api refuses while the group is still referenced. It does not name a sibling alternative or spell out when deleting is preferable to updating, so it falls short of a full when/when-not rubric.

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?

No annotations provided, so the description carries full burden. It discloses that the tool attempts to deploy, returns validation errors on failure, and stores output with an object ID. However, it lacks details on prerequisites (e.g., index must exist) and implications of deployment.

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 functional but somewhat verbose, with docstring-style param/returns and redundant mentions of object ID usage. It front-loads the main action but could be more streamlined.

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 return format and error handling but omits important context: it mentions 'in the given workspace' but the schema lacks a workspace parameter. Missing details on deployment effects and prerequisites like 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%, but the description adds a clear definition for the single parameter 'index_name' ('Name of the index to deploy'). This fully compensates for the missing schema description.

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

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

The description clearly states the tool deploys an index to production, using a specific verb and resource. It distinguishes from sibling tools like create_index (creates but doesn't deploy) and validate_index (validates but doesn't deploy).

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

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

The description implies the tool is for deploying an existing index but does not explicitly compare to alternatives like create_index or validate_index. No guidance on prerequisites or when to choose this tool over siblings.

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

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

No annotations provided, so description carries full burden. It discloses return behavior (validation result on failure, stored object ID) and how to use the object ID. However, it does not mention destructive actions, auth requirements, or side effects of deployment.

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 includes docstring-style parameter and return sections, making it somewhat lengthy (6 sentences). Information is front-loaded, but could be more concise.

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 no annotations, 0% schema coverage, and no output schema, the description provides parameter meanings, return value with object ID usage, and partial behavioral context. It lacks prerequisites (e.g., pipeline existence, permissions) but is fairly complete for deployment.

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 explains both parameters: pipeline_name is the name of the pipeline, version_id is optional and defaults to latest non-draft version. This adds significant meaning beyond the schema.

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

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

The description clearly states 'Deploys a pipeline to production,' which identifies the specific action and resource. It is distinct from sibling tools like 'create_pipeline' (which creates) and 'validate_pipeline' (which only validates).

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 does not provide guidance on when to use this tool versus alternatives (e.g., deploy_index, validate_pipeline). It only explains behavior on failure but no context for appropriate use.

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

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

The description does not disclose any behavioral aspects such as side effects, permissions, or whether the operation is read-only. While the name suggests a get operation, the description does not explicitly state that it is safe or free of side effects, and there are no annotations to fill this gap.

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 reasonably structured but contains redundant boilerplate about the object store and output formatting (e.g., repeating 'Use the object store tools...' twice). While not excessively long, this repetition could be trimmed for conciseness without losing essential information.

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

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

The description covers the tool's purpose, parameters, and return type, but it lacks context about why or when one would need a component definition (e.g., for inspecting inputs/outputs before pipeline creation). It does not explain the structure of the returned definition or its typical use in the broader workflow.

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 description provides meaningful explanations for both parameters. For component_type, it gives a concrete example. For haystack_version, it explains how to derive the value from the pipeline's dependencies. This adds clarity beyond the schema, which only lists types and required status.

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 function: 'Returns the definition of a specific Haystack component.' This is a specific verb-resource pair, and it distinguishes from sibling tools like get_pipeline or list_pipelines by focusing on component definitions.

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 does not provide guidance on when to use this tool versus alternatives. It lacks any mention of use cases, prerequisites, or scenarios where this tool is appropriate, leaving the agent to infer its purpose from the name and generic description.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses USD units, default sorting, pagination via total/has_more/page_number, default 30-day range, null cost_total meaning, organization-admin permission needs, and the important warning not to add Service and pipeline groups together. It also explains that __unattributed__ appears for usage outside a Service and that results are stored in the object store for later inspection.

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

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

The description is front-loaded with the purpose and organized into short paragraphs, and most content is necessary for an 11-parameter tool with no schema descriptions. It is still quite long, and the closing object-store/preview note plus some repeated Service-versus-pipeline explanation add bulk beyond the core call semantics.

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

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

Given 11 parameters, no annotations, no schema descriptions, and no output schema, the description is unusually complete: it covers permissions, scoping, grouping semantics, filtering behavior, pagination, return-preview/object-store handling, and edge cases like deleted pipelines and unpriced usage. The only notable inconsistency is the workspace reference not present in the schema.

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 document all 11 parameters, and it largely does: group_by values are explained, dates are inclusive/exclusive, sort fields and order are defined, services/providers/api_keys explain accepted ids versus names and filter combination semantics. The main flaw is that the prose refers to a workspace parameter ('Without workspace ... Use workspace') that is absent from the input schema, which could mislead an agent.

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: it reads LLM cost for a workspace or pipeline, grouped by model, pipeline, Service, or API key. This is clear enough to understand the operation, but it never names sibling tools such as get_cost_totals or get_cost_over_time, so the distinction relies on the reader inferring that this is the grouped breakdown rather than a total or time series.

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 useful usage context: use it to find what drove cost by model, pipeline, Service, or API key, and it explains organization-wide versus workspace scoping. However, it does not explicitly say when to choose this over get_cost_totals or get_cost_over_time, nor does it state exclusions beyond the Service/pipeline overlap warning.

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

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

With no annotations provided, the description carries the full burden and discloses key behavior: USD costs, one point per day with usage, omitted zero-usage days, null cost_total semantics for unpriced usage, inclusive/exclusive date bounds, and default ranges. It also states permission needs and the organization-admin-only behavior when workspace is omitted.

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 front-loaded and information-dense, with the primary purpose and usage context first. It is appropriately sized for the tool's complexity, though some parameter explanations and object-store boilerplate are slightly verbose.

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

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

There are no annotations, no output schema, and six sensitive query parameters, but the description covers defaults, permissions, filter semantics, limitations, return behavior, and the object-store preview mechanism. An agent has enough information to invoke the tool correctly without opening other documentation.

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 all six parameters, and it does. It documents date inclusivity, filtering combination logic, id sources from get_cost_breakdown, permission implications, and the organization-view restriction on pipeline_name and Service names.

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

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

The description states a specific verb, resource, and scope: reading LLM cost per UTC day for a workspace or one pipeline. It clearly distinguishes the tool from related siblings by naming get_cost_totals and get_cost_breakdown in relevant contexts.

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 such as seeing spending over time, finding when a cost spike started, or comparing periods. It also routes the agent to get_cost_totals for completeness checks and to get_cost_breakdown for obtaining provider, Service, and API key ids.

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

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

With no annotations, the description carries the full burden and does so: it discloses the admin-role requirement, the is_cost_complete lower-bound caveat with instructions to name unpriced_models and pending_generation_count, the asymmetry that total_requests counts queries rather than LLM calls, and that results are stored in the object store with an @obj id. That is behavioral detail an agent could not infer from the schema.

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

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

Front-loaded with the core purpose and defaults, and the paragraph-per-concern structure is easy to scan. It is long, though, and partly inflated by a Sphinx-style ':param'/':returns:' block that restates parameter info plus a generic object-store boilerplate tail that adds little.

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, no-output-schema tool this covers defaults, permission requirements, filter combination logic ('usage must match every kind you set, and any one value within a list'), and result handling. The missing piece is the absent ``workspace`` parameter the description depends on for its main scoping story.

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 compensate, and it largely does: inclusive start / exclusive end with a concrete September 2026 example, providers must be ids like bedrock_converse not display names, api_keys must be key ids never secret tokens, and services may be names or ids with different permission implications. The deduction is for referencing a ``workspace`` parameter that does not appear in the input schema, which would confuse an agent trying to scope to one workspace.

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 ('Reads the total LLM cost, tokens and requests') plus the exact scoping options (workspace, one pipeline, or whole organization) and a date range. The word 'totals' plus the scoping language distinguishes it from the sibling aggregates get_cost_over_time and get_cost_breakdown.

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

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

Explicitly says what question it answers ('how much a workspace or pipeline spent on LLM calls'), what the defaults are (last 30 days, whole organization), and what constraint applies (whole-org view requires the organization admin role). It also names exclusions and workarounds: pipeline_name and Service names can't be used in the org view, pass Service ids instead, and it points to get_cost_breakdown as the source of ids.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It transparently mentions that the output is automatically stored, returns an object ID, and can be referenced elsewhere. It also notes 'ComponentDefinitionList model or error message string.' It does not explicitly state read-only behavior, but the get semantics imply it. The disclosure of the object store side effect is an informative behavioral trait beyond what annotations would 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 organized with the main purpose first, followed by parameter documentation, return type, and additional usage notes. It is somewhat verbose but each sentence adds value, such as storage behavior and object ID usage. It is appropriately sized for a tool with one parameter and a clear output.

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

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

Despite no output schema, the description fully clarifies what the tool returns (ComponentDefinitionList model or error string) and how to further interact with the result (object store tools). It covers all necessary aspects for a simple list tool, including the optional parameter handling and the storage mechanism. No critical 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 compensates by explaining the parameter 'haystack_version' in detail: 'Pass the same version as specified in the pipeline yaml's `dependencies` section.' This adds meaning beyond the schema, which only shows the type. The explanation is sufficient for understanding how to set it correctly.

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: 'Get a list of all installed custom components.' This is a specific verb ('Get') and resource ('list of installed custom components'), and it distinguishes from siblings like list_custom_component_installations, which focuses on installation logs. The purpose is unambiguous and effectively differentiates from similar tools.

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

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

The description implies usage context ('get a list of all installed custom components') but does not explicitly state when to prefer this tool over alternatives like search_component_definitions or get_component_definition. There is no guidance on exclusions or comparisons, though the purpose is clear. It gives basic instructions on the optional haystack_version parameter but lacks explicit when-to-use 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 no annotations supplied, the description carries the burden and does disclose meaningful behavior: the result is automatically stored, a formatted preview with an @obj_ ID is returned, and nested properties require the object store tools. It also states an error message is returned instead of the Dataset. Missing are permission/read-only expectations and any note on large datasets or truncation of the preview.

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

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

The opening sentence is well front-loaded, but Sphinx artifacts (':param', ':returns:') leak into agent-facing text, and the object-store advice is spread over four separate sentences that repeat the same idea. Roughly a third of the text could be collapsed into one 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?

For a single-parameter read with no output schema, the description covers the return shape (test_case_id, session_id or inputs, expected, setup/cleanup), the object-store retrieval path, and the error case. Only the parameter's origin/format and access expectations are left unstated.

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

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

Schema description coverage is 0%, so the description must compensate, and it only says ':param dataset_id: The Dataset's id.' — essentially a restatement of the parameter name/title. It does not clarify the id format or where the id comes from (e.g., a prior list_datasets call).

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 and resource ('Fetches one Dataset') and immediately scopes the payload ('with all its test cases, in the order an Experiment replays them'), which distinguishes it from list_datasets and from experiment-level tools. The agent knows exactly what it gets back without opening the schema.

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

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

Guidance is given for the output side-channel ('Use the object store tools in combination with the object ID', 'pass this result to other functions'), but there is no guidance on when to call this versus list_datasets, get_experiment, or update_dataset. Usage is implied by 'one Dataset' but alternatives are never named.

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

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

With no annotations, the description carries the full burden, and it does disclose an important non-obvious behavior: the result is stored in an object store and returned as a formatted preview with an object ID. However, it says nothing about permissions, error conditions beyond 'error message', or whether the read is side-effect free.

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 and clear, but the docstring-style block is padded: ':returns: Deployment details or error message' is followed by three sentences that all circle the same object-store/object-ID idea, with the last two largely redundant.

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

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

There is no output schema, so the description is right to describe the return mechanism (object ID, preview, chaining into object-store tools). It stops short on other essentials such as error handling and where the deployment_id comes from, leaving gaps for a tool embedded among ~60 siblings.

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

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

Schema description coverage is 0% and the single param has no schema description, so the description must compensate. It offers only 'ID of the deployment to fetch', which restates the parameter name rather than clarifying format, source, or where to obtain it.

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

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

States a specific verb and resource ('Fetches details for a specific deployment') and adds the scope of what is returned (active revision, runtime status). This distinguishes it from list_deployments and get_deployment_revision without naming them, but the differentiation is implicit rather than explicit.

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

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

The description never says when to use this tool versus the many siblings (get_deployment_revision, get_deployment_stats, get_deployment_metrics, list_deployment_revisions). Usage is only inferable from 'specific deployment', so an agent gets no routing guidance.

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

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

No annotations exist, so the description carries the full burden. It does disclose a real behavioral trait: output is auto-stored and returns an object ID (@obj_123) that feeds object-store tools. That is valuable and non-obvious. It does not, however, cover auth/permission requirements, read-only nature, or rate limits.

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

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

The core purpose is front-loaded, but the object-store explanation is repeated across three sentences ('referenced in other functions', 'use the object store tools', 'pass this result to other functions') with overlapping meaning. The docstring-style ':param/:returns' formatting is also less scannable than prose.

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

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

With no annotations and no output schema, the description does cover parameter meaning and the return/object-store mechanism, which is the critical missing structured data. It falls short on usage routing relative to get_deployment_stats and on any access/permission context, leaving an agent with gaps before invoking 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 schema provides only bare titles, and the description compensates by documenting all three parameters, including the unit for start_ms/end_ms ('unix milliseconds'). That unit detail is genuinely additive. Deployment_id is described only generically ('ID of the deployment'), so it is not perfect.

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 gives a specific verb and resource: 'Fetches per-replica CPU/memory usage, resource limits, and replica counts for a deployment.' An agent immediately knows the resource and the metric types returned. However, it does not distinguish itself from the sibling get_deployment_stats, which an agent could plausibly confuse with it.

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

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

There is no when-to-use guidance and no mention of alternatives or prerequisites. With siblings like get_deployment_stats and get_deployment present, the description should state what selects this tool over those, but it leaves that entirely to inference.

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

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

With no annotations, the description carries the full burden, but it does disclose real behavior: the result is auto-stored, returned as a formatted preview with an object ID, and nested properties are reached via object-store tools. It omits permission/auth requirements and only vaguely gestures at errors ('or error message').

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 lead sentence is well front-loaded, but the trailing block repeats the object-store idea across four sentences ('automatically stored', 'referenced in other functions', 'use the object store tools', 'pass this result to other functions') without adding new 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-param fetch with no output schema, the description covers the return shape (revision + config YAML) at a high level and explains the object-store handoff. It is missing selection guidance and the meaning of the two IDs, which are the main gaps an agent would hit.

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, yet the :param lines merely restate the names ('ID of the deployment', 'ID of the revision to fetch') without format, source, or how to obtain them. It adds almost no meaning beyond the parameter names.

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 ('Fetches a single deployment revision') and adds scope detail ('including the pipeline configuration YAML it serves'), which clearly separates it from the sibling list_deployment_revisions. An agent can identify the operation without opening the schema.

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

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

There is no statement of when to choose this over siblings like get_deployment, list_deployment_revisions, or activate_deployment_revision, and no prerequisites or exclusions. The object-store notes describe what to do with the result, not when to call this tool.

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

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

With no annotations, the description carries the full burden. It does add genuinely useful behavioral context: the result is auto-stored in an object store and returned as an object ID (@obj_123) that can be fed into other functions and inspected via object-store tools. What it omits is the read-only nature, any authorization requirements, and whether values are nil for inactive deployments.

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 :param/:returns block is efficient, but the object-store tail is spread over three sentences that partially restate each other ('stored and can be referenced', 'use the object store tools', 'pass this result to other functions'). Front-loading is good, but there is redundancy that could be compressed.

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

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

For a 4-param tool with no output schema and no annotations, the definition covers parameters well and explains the important non-obvious behavior that the actual data lives behind an object ID. It is nearly complete; the remaining gap is distinguishing it from the metrics sibling and any dependency on deployment state.

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, and it largely does: each of the four params gets a :param line with units, bounds (1-90), defaults (30, DAY, UTC), and the enum values for granularity. This is meaningfully richer than the bare schema titles, though it doesn't explain time_zone's effect on bucket boundaries beyond 'bucket the series'.

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 and enumerates exactly what is returned: query volume, outcome split, and run durations for a deployment. That is a clear purpose. However, it never distinguishes itself from the sibling get_deployment_metrics, which an agent could easily confuse with stats, so it falls short of a 5.

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

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

There is no when-to-use guidance, no prerequisites (e.g., the deployment must be active), and no reference to alternatives such as get_deployment_metrics or get_deployment. The agent is left to infer applicability purely from the tool name.

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

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

With no annotations, the description carries the full burden and does well: it defines the status/outcome state machine (ENDED + SUCCEEDED yields metrics, ERRORED means the evaluator code broke and points to error_detail, FAILED never completed and can be re-run). It also discloses that results are persisted to the object store and returned as a preview with an object ID, though permissions and read-only guarantees are unstated.

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 behavior is front-loaded, but the text carries Sphinx-style ':param' and ':returns' markup and three separate sentences about object IDs and the object store, which repeat the same point. Trimming the duplicated storage/object-ID text would sharpen it.

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

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

There is no output schema, so the description must convey return semantics, and it does: status, outcome, metrics, error_detail, and the object-store preview are all described. What remains missing is how run state is obtained if not ENDED (polling cadence, timeouts) — minor 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?

Schema description coverage is 0%, so the description must compensate. It explains the provenance of evaluation_run_id (from run_evaluator or list_evaluation_runs), which is genuinely useful, but pipeline_name is only glossed as 'Name of the pipeline' with no format or qualification guidance.

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 ('Reads one Evaluation Run') plus scope: current progress versus post-run findings. It also names the producing siblings (run_evaluator, list_evaluation_runs), so an agent can immediately tell this apart from the listing tool.

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

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

Explicitly says to use it to follow a run that run_evaluator returned while still in progress, and where the evaluation_run_id comes from. It lacks an explicit exclusion (e.g., 'use list_evaluation_runs to enumerate runs instead'), which keeps it below a 5.

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

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

No annotations exist, so the description carries the burden, and it discloses real behavioral traits: tries expire after an hour (TTL), an EXPIRED state exists, and it may return 'an error message'. It doesn't cover auth or idempotency, but the lifecycle and failure semantics are genuinely useful beyond structured fields.

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

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

Front-loaded with the core purpose and expiration behavior, then the params. The Sphinx-style :param:/:returns: tags are slightly redundant with the prose but compact and 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?

With no output schema, the description correctly states the return ('The try report, or an error message'), and both required params are covered. For a two-param read tool this is essentially complete, with only auth/prerequisite detail missing.

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

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

Schema coverage is 0%, so the description must compensate, and it documents both parameters. Critically, it explains that try_id originates from try_evaluator, adding meaning the bare string-typed schema does not convey.

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

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

States a specific verb ('Reads') and resource ('an ad-hoc try'), and ties it directly to the sibling try_evaluator that produced the try. An agent can distinguish it from try_evaluator (which initiates) without opening either schema.

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

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

Explicitly establishes the workflow: try_id comes 'from try_evaluator', so this is the retrieval step after a try is handed back. It also gives a concrete remedy on EXPIRED (re-run try_evaluator). It lacks an explicit 'do not use this to start a try' exclusion, but the context is clear.

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

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

No annotations are provided, so the description carries the full burden, and it does a good job: it discloses exactly what is returned in each mode, that source is omitted unless version_id is set, that errors come back as a message, and the object-store side effect with an @obj_123 ID. It does not cover permissions or rate limits, hence not a 5.

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

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

The first sentence is well front-loaded, but the piece is padded: the :param version_id line restates the opening paragraph, the :returns line restates the outcome, and the closing two sentences about the object ID duplicate the earlier object-store note. Structure is conventional but several sentences do not earn their place.

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

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

With no output schema, the description must explain return values, and it does so for both modes plus the object-store preview and cross-function reuse. For a two-parameter read tool this is nearly complete; only permission/error-handling detail 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, and it does: both parameters are documented via :param lines, with version_id carrying real behavioral meaning (it controls whether python_code is returned). evaluator_id's semantics as "The Evaluator's id" is thin but adequate alongside the required-parameter constraint.

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 ("Fetches one Evaluator, or one of its versions with the Python source") and immediately distinguishes the two operating modes by the presence of version_id. It implicitly contrasts with the list_evaluators sibling via "one Evaluator," but never names the alternative explicitly.

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

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

Gives concrete conditional guidance: without version_id you get every version newest-first without source; with version_id you get that version's python_code, and it tells you to pass latest_version.evaluator_version_id to read current source. No exclusion or explicit alternative tool is named, but the when-to-use context is clear.

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

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

No annotations are supplied, so the description carried the full burden and does disclose a lot: the status lifecycle (REPLAYING, SCORING, then ENDED/FAILED), per-side fields run_counts, scoring_counts, error and experiment_run_id, retry semantics for failed replays/scorings, and the cost signal 'Free to call.' That is strong behavioral context, but it stops short of stating permission/auth requirements. A 3 reflects solid disclosure with that one notable gap.

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 prose is dense and front-loaded, with the state-machine and per-side field explanation earning its place. The trailing block about automatic object storage, formatted previews, @obj_123 IDs and object-store tools is generic boilerplate repeated across tools, and the ':param'/':returns:' Sphinx fragments mixed with prose read awkwardly.

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

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

With no output schema, the description does the work of describing return contents field-by-field and notes what is deliberately omitted (scored Sessions), which is exactly what an agent needs. The only shortfall is the absence of any permission or access-level statement for a read operation.

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

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

One parameter at 0% schema coverage, so the description must compensate and it partly does: ':param experiment_id: The Experiment's id, from list_experiments' adds provenance the schema lacks. It does not add format details (ID shape, whether an object ID is accepted), leaving the agent with a pointer but no syntax guidance.

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 and resource: 'Reads one Experiment: its test cases and how far each side has got.' It immediately scopes what is and isn't returned, letting an agent distinguish it from get_experiment_results and get_experiment_run 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?

Explicitly states when to call it ('follow an Experiment after create_experiment, update_experiment or a rerun, and to see why a side failed') and routes to alternatives by name: get_experiment_results for per-test-case Sessions, rerun_failed_experiment for retries, get_session_replay for diagnosing a failed replay. Exclusions are stated, not inferred.

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

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

With no annotations at all, the description carries the full burden and does so: results are partial while ``status`` is REPLAYING or SCORING, ``aggregates`` is empty until scoring runs end, ``errored`` counts mean the Evaluator's own code broke, ``unknown`` means no judgement, and comparability failures must be reported as no-change. It also discloses the object-store side effect (auto-stored output, preview with an ``@obj_123`` id), which is behavior an agent must know before calling.

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 first sentence is front-loaded with the core purpose and the dense middle is largely necessary return-value documentation given there is no output schema. Some density could be trimmed (the ``pipeline_metrics`` aside, the repeated 'each side's' phrasing) and the trailing object-store boilerplate does not earn much space, but overall the content justifies its length.

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

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

With no output schema and only 0% parameter coverage, the description compensates by documenting the return structure field by field: ``metrics``, ``delta``/``delta_pct``, ``change``, ``paired_test_cases``, ``pipeline_metrics``, per-test-case Session breakdowns, ``headline``/``normalized_means``, ``comparable`` and ``aggregates``. An agent can both call the tool and interpret its output without further documentation.

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 compensate. ``max_test_cases`` is explained with a crucial semantic detail — '``metrics`` still cover every test case' — which prevents the agent from assuming metrics are truncated too. ``experiment_id`` is only restated ('The Experiment's id'), but that parameter is self-evident, so the gap is minor.

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 gives a specific verb and resource plus the shape of the payload: 'Reads an Experiment's results: each Metric, candidate against baseline, then each test case.' It is clearly a results-retrieval tool, distinguishable from metadata tools like get_experiment or run-management tools like list_experiment_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?

It routes the agent explicitly: find the experiment with ``list_experiments`` and resolve evaluator ids with ``list_evaluators``. It also gives conditional usage rules ('Say a Metric improved or regressed only from ``change``', 'When ``comparable`` is false ... report no change'). It stops short of naming sibling result tools such as get_experiment_run or get_evaluation_run as alternatives, so it is strong but not fully disambiguating.

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 no annotations supplied, the description carries the full burden and does so thoroughly: it explains that 'errored' means Evaluator code breaking rather than a low Metric, that 'failed' cells can be retried, that aggregate/usage/composite are null until the run ends or unless cost_status is 'priced', and that run.selection (SAMPLED vs HAND_PICKED) determines whether traffic-wide inference is valid. It also discloses the important side effect that output is auto-stored and returned as an @obj_123 reference for reuse via object store tools.

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?

It is front-loaded with the core purpose, but the body is a dense, unbroken prose block covering return fields, filter semantics, and object-store boilerplate without headings or bullets, making it hard to scan. Nearly every sentence is substantive, so the length is largely earned by the complexity, but the structure could be much tighter.

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

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

For an 8-parameter, no-output-schema tool, the description explains return values in unusual depth, including null conditions and exactly which fields filters do and do not narrow. Minor gaps remain around error behavior beyond 'The run report, or an error message' and any access/permission requirements.

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, and it does: every one of the 8 parameters has a documented meaning, including that max_rows limits rows but summaries still cover every row, and that origin maps to Service/pipeline API/Playground. The descriptions for pipeline_name, metric_group_id, and run_id are terse ('Name of the pipeline', 'The run's id'), which is the main residual gap given zero schema coverage.

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

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

The opening sentence states a specific verb and resource ('Reads one scoring run') and then enumerates exactly what is returned: cell outcomes, a per-Metric summary, and the grid rows. It further anchors the concept ('a scoring run is a Metric Group judging chosen Sessions of one pipeline'), so an agent can distinguish it from list-level siblings without opening the schema.

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

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

It gives a concrete discovery path for the required identifiers ('find one with list_metric_groups (last_run) or list_experiments (a side's scoring_runs)'), which is actionable routing guidance. It does not, however, contrast this tool with close siblings such as get_experiment_results, get_evaluation_run, or list_experiment_runs, nor state when not to use it.

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 no annotations, the description carries the full burden. It does disclose the return shape ('String representation of the object or of the value at path'), which is valuable given there is no output schema. But it omits failure behavior (missing id, invalid path), any permission/auth requirements, and any side-effect statement for this read operation.

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, then progressively adds the id mode, the path mode, and parameter docs. The JSON example is worth its space; the format is efficient overall, with only minor redundancy between the prose path explanation and the `:param path:` 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 tool with no annotations and no output schema, the description covers the essentials (what it returns, both parameter formats), which is more than minimal. But it stops short of error/edge-case behavior and any resource-identification guidance for deciding between this and the other object-store tools.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does: it specifies the id format (`@obj_001`) and two accepted path syntaxes (`access.to.attr` and `["access"]["to"]["attr"]`) with a concrete example. This meaningfully compensates for the undocumented schema, though the empty-string default for `path` is never explained.

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 ('fetch an object from the object store') and immediately operationalizes it with two retrieval modes. It is clear on its own, but never names the adjacent siblings (get_slice_from_object_store, sed_object_store, grep_object_store) to draw the boundary, so an agent still has to infer which store tool applies.

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

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

The description explains the two ways to call it (by id, or by id plus nested path with a worked example), which is genuine usage guidance. However, it gives no when-to-use vs the many store siblings and no exclusions, so the routing decision 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?

No annotations exist, so the description carries the full burden. It usefully discloses that output is auto-stored, returned as an object ID preview, and that nested properties require object store tools, but says nothing about auth requirements, read-only nature, or error conditions beyond 'an error message'.

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, but the entry mixes Sphinx-style ':param:'/':returns:' directives with prose and then spends three sentences on object store mechanics. Some redundancy between ':returns:' and the object-ID paragraphs.

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

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

With no output schema and no annotations, the description does the needed lifting by describing the return value ('index configuration or an error message') and the object-ID indirection pattern. It is nearly complete for this simple one-parameter read.

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% and the single parameter has no schema description, so the description must compensate. It does document index_name as the 'Unique name of the index to fetch', which adds the uniqueness constraint but no format or naming convention details.

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 ('Fetches') and resource ('detailed configuration information for a specific index'), anchored by the unique index_name. It is clearly differentiated from list_indexes by the singular scope, though no sibling is named explicitly.

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

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

There is no explicit when-to-use vs. list_indexes/update_index guidance, but the description does give downstream workflow direction ('Use the object store tools in combination with the object ID'). Usage is implied rather than stated.

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

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

The description discloses that the output is stored and returns an object ID for further use, implying a read operation. However, with no annotations, it does not explicitly confirm no side effects or state the exact behavior beyond output handling.

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 adequate but contains some redundancy (e.g., mentioning logs twice). It is structured as a paragraph but could be more streamlined.

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 no parameters or output schema, the description sufficiently explains the output format and how to use it with object store tools. It lacks details on error scenarios but covers the essentials.

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

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

No parameters are defined, so the schema provides full coverage. The description adds value by explaining the output storage and object ID usage, meeting the baseline for a zero-parameter tool.

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 retrieves logs from the latest custom component installation. The name and description are consistent, but no explicit differentiation from sibling tools is provided.

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 includes instructions on using the output with object store tools but lacks guidance on when to choose this tool over alternatives like list_custom_component_installations or get_custom_components.

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 no annotations, the description does real work: it discloses the side effect that results are auto-stored as an object with an ID (e.g. @obj_123) to be read via object-store tools, and that include_price requires read access to costs and silently omits price for models like Azure deployment-named ones. Missing are explicit read-only framing, auth scope beyond costs, and ordering/pagination edge 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 is front-loaded, then parameters, then return behavior, so scanning order is correct. It is somewhat long and the boilerplate object-store paragraph plus ':returns' line add bulk, but nearly every line carries actionable 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 six-optional-parameter list tool with no output schema and no annotations, the description covers purpose, filtering semantics, cost/permission caveat, pagination and the shape of the returned result (preview + object ID). An agent has enough to call it correctly and know how to retrieve nested details.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: every one of the six parameters is documented with semantics beyond the schema — limit as per-page cap, page_number starting at 1, connected as integration-status filter, provider as case-insensitive exact match accepting well-known or arbitrary provider strings, model as case-insensitive substring match, and include_price's units (USD per 1,000 tokens, input/output/cache).

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 gives a specific verb and resource ('Lists the models including their configuration options') plus the scope ('available for use in a workspace's pipelines and indexes'). It immediately separates itself from sibling list tools such as list_pipelines, list_indexes and get_custom_components.

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 names the discovery use case: finding model names/providers, available configuration options, and default configuration when setting up chat generators. There are no explicit exclusions or named alternatives, but the usage context is unambiguous.

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?

No annotations are provided, so the description carries the burden. It discloses that the output is automatically stored, returns a formatted preview with an object ID, and can be passed to other functions. It also mentions error messages. This is valuable beyond the schema, though it stops short of stating permissions or explicit read-only safety.

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 moderately sized but contains redundancy; two sentences about using the object ID could be merged. The use of `:param` and `:returns` is conventional, but the instructions are somewhat scattered.

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 one-parameter tool, it covers the return format and how to use the object ID, but it lacks explicit usage guidance versus siblings and does not elaborate on error conditions beyond a generic message. The overall context is adequate for basic use but not comprehensive.

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 must compensate. However, it only restates the parameter name ('The name of the pipeline to fetch') and adds 'unique', which adds little meaning beyond the schema. No format, constraints, or examples are provided.

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

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

The description clearly states it 'Fetches information for a specific pipeline' and identifies the resource by the unique `pipeline_name`, distinguishing it from sibling tools like `list_pipelines` (fetching all) and `get_pipeline_version` (a version-specific resource).

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

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

It implies usage when you have a specific pipeline name, but does not explicitly mention when to prefer this over alternatives, nor does it state exclusions. The guidance about using object store tools is about post-processing, not tool selection.

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?

No annotations are provided, so the description carries the burden. It explains output is automatically stored and returns an object ID, which is key behavioral info. It could be more transparent about permissions or format.

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

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

The description is well-structured with a front-loaded purpose and parameter docs, but has slight redundancy between 'Fetches logs' and 'Retrieves log entries'.

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?

It covers parameters and output usage but lacks details on return format and pagination mechanics (how to get the first cursor). Given no output schema, this is a 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%, but the description fully compensates by explaining each parameter's purpose (pipeline_name, limit, level, after) with clear semantics.

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

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

The description clearly states 'Fetches logs for a specific pipeline' with a specific verb and resource. It distinguishes from siblings as no other tool fetches logs.

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 mentions 'useful for debugging pipeline issues or monitoring pipeline execution', providing clear context. However, it lacks explicit exclusions or alternative comparisons.

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 no annotations, the description carries the burden and discloses important behaviors: returns all spans, excludes component input/output, includes timing and failure details, and automatically stores output with an object ID. It clearly signals a read-like operation via 'Retrieves' and explains the side effect of storage.

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 strictly necessary, with some redundancy (query_id source is mentioned twice). However, it is well-structured with a front-loaded purpose, clear param block, and separate usage guidance. Every major section 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?

Given the absence of annotations and output schema, the description provides a comprehensive context: what is returned, what is excluded, error handling, object store integration, and how to reference the result. It covers the tool's role in the broader workflow and directs users to related tools when needed.

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% (no descriptions in properties), but the description fully explains both parameters. pipeline_name is simply 'Name of the pipeline,' and query_id is given a detailed definition with instructions to obtain it from the query_id/search_history_id field of list_pipeline_traces or list_pipeline_search_history responses.

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: 'Retrieves the Haystack pipeline run trace including all spans for a single search history record.' It clearly differentiates from sibling tools by focusing on the full trace for a single query, and mentions alternatives for other granularities.

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

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

Explicitly states when to use ('Use this to deep-dive into a specific query run') and how to obtain required identifiers ('obtainable from list_pipeline_traces or list_pipeline_search_history'). It also provides concrete alternatives: 'For a targeted look at one span... use get_pipeline_trace_span_tags; for the logs, use get_pipeline_trace_logs.'

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 no annotations provided, the description carries the full burden. It discloses the return structure (logger, level, message, timestamp, extra fields), the exclusion of errors outside the pipeline, and the automatic storing of output with an object ID for reference. It does not mention pagination or auth, but provides substantial behavioral context beyond a simple read-only claim.

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-structured with clear paragraphs and param documentation. Some redundancy exists around the object ID mention ('Returns a formatted preview' and 'Use the returned object ID'), but the content is all relevant and earned.

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 2 parameters, no output schema, and no annotations, this description is remarkably complete. It covers purpose, use cases, parameter semantics, expected return format, error boundaries, related tools, and how to reference the result. It leaves little ambiguity for an AI agent attempting to invoke the 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?

Although the input schema provides no descriptions for either parameter (0% coverage), the description compensates fully by defining pipeline_name as 'Name of the pipeline' and query_id as 'UUID of the search history query', and additionally tells users where to obtain query_id. This exceeds schema-level information.

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 explicitly states 'Retrieves the log entries for a single Haystack pipeline run trace', which is a specific verb+resource combination. It distinguishes from siblings by naming the alternative get_pipeline_logs and explaining when each should be used.

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 says when to use this tool (to diagnose warnings/errors emitted during a run) and when to use get_pipeline_logs instead (pipeline startup errors, configuration issues). It also explains how to obtain query_id from list_pipeline_traces or list_pipeline_search_history.

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 no annotations, the description carries the full burden. It discloses the return type (tag dictionary or error message), the automatic storage of output, and the object ID behavior. It lacks details on permissions or rate limits, but covers key behavioral aspects.

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 clear sections (purpose, usage hints, param docs, returns) and uses formatting (bold, code) for readability. It is somewhat lengthy but each section adds value.

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 covers purpose, usage context, parameter semantics, return behavior, and object store integration. Given no output schema or annotations, it is fairly complete, though it could include an example of the tag dictionary structure.

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

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

Despite 0% schema coverage, the description explicitly defines each parameter in the :param: lines, including types and purpose (e.g., 'UUID of the span whose tags to retrieve'). This compensates well for the schema's silence.

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 action ('Retrieves all tags for a single span') on a specific resource ('within a Haystack pipeline run trace'), clearly distinguishing it from sibling tools like get_pipeline_trace.

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 ('Use this to inspect one component run in detail') and explains how to obtain the required parameters from other tools (get_pipeline_trace, list_pipeline_traces). It does not explicitly mention when not to use it, but the guidance is strong.

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 no annotations, the description discloses that the output is automatically stored in the object store and returns an object ID for referencing. It explains how to use the result with object store tools. However, it omits authentication needs, rate limits, or side effects, though the operation is likely read-only.

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 informative with a clear purpose, parameter docs, and output usage notes. It is slightly lengthy due to repeating param docs that could be in the schema, but overall front-loaded with the main action. Every sentence adds value.

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 fetch tool with no output schema, the description explains the return format (object ID) and how to use it. It covers the basic workflow but lacks details on error handling or prerequisites. Given the tool's simplicity, it is reasonably complete.

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

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

The schema has 0% description coverage, but the description includes explicit parameter documentation: ':param pipeline_name: Name of the pipeline.' and ':param version_id: UUID of the version to fetch.' This adds crucial meaning beyond the schema's property 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?

The description clearly states it fetches a specific pipeline version by ID, using the verb 'fetches' and specific resource 'version'. It distinguishes from siblings like 'list_pipeline_versions' (which lists all versions) and 'patch_pipeline_version' (which modifies).

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 (fetching a specific version) but does not explicitly guide when to use this vs. alternatives like 'list_pipeline_versions' for multiple versions or 'get_pipeline' for the pipeline itself. It mentions using object store tools for nested properties, which helps for further interaction.

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?

No annotations are provided, so the description must convey behavior. It states the secret value is not returned, output is stored, and an object ID is returned for referencing. It lacks details on auth needs, rate limits, or error handling.

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 moderately concise but contains redundant phrasing (e.g., 'Use this tool to get information about a specific secret' reiterates the purpose). It front-loads the core action but could be tighter.

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 tool with one parameter and no annotations, the description covers retrieval, security nuance, and output format. However, it omits specifics like what metadata is returned, error case handling, and explicit object store usage instructions.

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%. The description adds minimal semantics by calling secret_id 'the unique identifier of the secret to retrieve,' which is a slight improvement over the schema's bare title. Given the low coverage, more elaboration is needed.

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 function: 'Retrieves detailed information about a specific secret by its ID.' It differentiates from siblings like list_secrets by emphasizing 'specific secret' and 'by ID'.

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: 'Use this tool to get information about a specific secret when you know its ID.' It also notes that the secret value is not returned for security reasons, implying alternative uses for other data.

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

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

With no annotations provided, the description carries the behavioral burden well: it discloses that the call is free, enumerates the returned fields (status, error_detail, setup_logs, cleanup_logs, session_id, source_session_id, test_case_id, trace_ids), and states that only FAILED runs are retryable. It does not cover permission or rate-limit behavior, which keeps it short of a 5.

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

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

The core behavior and id-sourcing guidance are front-loaded, and the field enumeration earns its length by documenting an otherwise undocumented return value. The 'Experiment support, for when you need it' preamble and the trailing :param/:returns docstring lines add some boilerplate.

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

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

There is no output schema and zero schema coverage, so the description has to describe both inputs and returns, and it does: it names every returned field, the possible status values, and the retry path. Nothing an agent needs in order to call and interpret this tool 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, and it does for the non-obvious parameter: it explains that replay_run_id is the run's session_replay_run_id and shows two concrete ways to obtain it. pipeline_name is only glossed as 'Name of the pipeline', which is thin but low-risk given the parameter's obviousness.

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 'Reads one replay run' gives a specific verb and resource, and the follow-up defines the tool's scope as experiment-replay debugging. It does not explicitly distinguish itself from adjacent read tools like get_experiment_run, though it clarifies the relationship by explaining that get_experiment_run supplies the id.

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

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

The description states exactly when to use it (to see why an Experiment's replay failed or looks wrong), where to get the required replay_run_id (a row's session_replay_run_id in get_experiment_run, or replay_session), and names the follow-up alternative rerun_failed_experiment for FAILED runs. Routing and alternatives are explicit rather than inferred.

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

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

The description indicates the return type (string representation) but does not disclose error handling (e.g., invalid indices) or side effects. With no annotations, more details are expected.

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 and includes a structured docstring format, though the parameter tags are slightly verbose for a tool description.

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

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

The description adequately covers the tool's functionality and parameters, but lacks information on error cases and does not differentiate from sibling tools in the object store family.

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

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

All four parameters are explained with purpose and defaults/optionality, adding significant value since the input schema has 0% description coverage.

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

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

The description clearly states the action (extract) and resource (slice from object store), which is distinct from siblings like get_from_object_store (whole object) and grep_object_store (search).

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 explicit guidance on when to use this tool versus alternatives such as get_from_object_store or grep_object_store; usage context is only implied by the description.

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

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

Even without annotations, the description discloses key behavioral traits: the output is automatically stored, a preview with an object ID is returned, and the ID can be used with object store tools or passed to other functions. This goes beyond just 'fetches template' and aids the agent in understanding the return format and side effects.

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

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

The description is concise and well-structured: main purpose first, then param explanation, return behavior, and usage tips. The docstring-style formatting is clear, and each sentence adds value. Slight room for improvement by front-loading more critical info.

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 get-template tool with one parameter and no output schema, the description covers purpose, parameter, return value (including object ID utility), and error handling (indicated by 'error message'). This is sufficiently complete for the complexity level.

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 0% description coverage, so the description must compensate. It provides a basic docstring for the only parameter, 'template_name', stating 'The name of the template to fetch.' This adds meaning beyond the schema (which only gives title and type), but lacks details on format, allowed values, or 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 explicitly states the action ('Fetches detailed information') and the resource ('specific pipeline or indexing template'), identified by a unique name. It clearly distinguishes from sibling tools like list_templates or search_templates.

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

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

The description implies when to use this tool (to get details of a single template by name), but it does not explicitly state when not to use it or point to alternatives (e.g., list_templates for listing, search_templates for searching). No direct comparison to siblings.

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

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

No annotations are provided, so the description carries the full burden. It describes the output format (object ID, preview), explains how to access nested properties via object store, and mentions error messages. It implies a read-only operation, but does not explicitly state non-destructive behavior. Overall, it is transparent for a simple get operation.

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

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

The description is well-structured, front-loading the purpose and then detailing output and usage. It is slightly verbose with repetition (e.g., 'This tool retrieves' and 'Use this when'), but every sentence adds value. The docstring-style parameter description is included.

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 no output schema and a simple single-parameter input, the description provides comprehensive context: return format (object ID, preview), instructions for accessing nested properties via object store, and mention of error messages. It fully compensates for missing structured metadata.

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, but the description adds meaning by stating 'The name of the workspace to fetch details for.' This clarifies the parameter's purpose beyond the schema's title 'Workspace Name' and indicates it is required.

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 fetches detailed information for a specific workspace by name. It uses a specific verb ('Fetches') and resource ('workspace'), and distinguishes from siblings like list_workspaces (list all) and create_workspace (create).

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 provides clear context for when to use the tool: 'Use this when you need detailed information about a particular workspace.' It does not explicitly exclude alternative tools like list_workspaces, but the purpose is clear enough.

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 no annotations provided, the description carries the full burden. It discloses that the tool returns matches with surrounding context (similar to grep) and explains each parameter's role. It does not mention side effects, authentication, or rate limits, but the behavior is clearly described as a read-only pattern search with optional 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 concise, starting with the main purpose and then listing parameters. It is front-loaded and each sentence adds value. The parameter list is slightly redundant with the schema but aids readability.

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

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

Given the tool's complexity (4 parameters, 2 required, no output schema), the description is complete. It explains input format, optional parameters, and return value (matches with context or no-matches message). No gaps are apparent.

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?

Despite 0% schema description coverage, the description adds meaningful explanations for each parameter: 'object_id' format (@obj_001), 'pattern' as regex, 'path' as navigation to nested attribute, and 'case_sensitive' default. This significantly enhances the schema's minimal definitions.

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: searching for a regex pattern in a string stored in the object store. It uses a specific verb ('search for') and resource ('string stored in the object store'), and distinguishes itself from sibling tools like 'get_from_object_store' and 'sed_object_store' by mentioning 'regex pattern' and 'similar to grep'.

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 on when to use the tool (search for patterns in object store strings) and includes optional parameters (path, case_sensitive) that guide usage. It does not explicitly state when not to use it or compare to alternatives, but the provided context (e.g., 'similar to grep') implies appropriate use cases.

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