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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds only that the run must be running, which is mild context. It omits the force-cancel scenario, the 400 rejection on premature force calls, and any idempotency or account-scoping behavior described in the schema.

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

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

The description is a single front-loaded sentence with no waste. However, its extreme brevity for a destructive operation means it may be under-specified rather than perfectly 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?

For a destructive cancel tool with no output schema, the description should surface the force-cancel nuance and account-scoping behavior that an agent needs before invoking. Those details live only in the schema, leaving the top-level description incomplete. The annotations cover safety but not operational context.

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

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

Schema coverage is 67%, with the force flag and account header documented in detail inside the schema itself. The description contributes only 'by its ID,' which restates the schema's pipeline_run_id description and adds no new parameter meaning. Since structured fields already do most of the work, a baseline 3 is appropriate.

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

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

The description states a specific verb and resource: cancel a running pipeline run, identified by its ID. This is clear enough for an agent to distinguish it from siblings like start_pipeline or pause_pipeline. It stops short of 5 because it does not clarify the relationship to the force-cancel path or contrast with any sibling explicitly.

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

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

There is no guidance on when to use this tool versus alternatives such as pause_pipeline or start_pipeline, nor any prerequisite conditions. The description only says it cancels a running run, which the name already implies. No when/when-not information is provided.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/safe profile is known. The description usefully adds the side effect that the first environment in a workspace becomes the default, but says nothing about name uniqueness, idempotency, or auth requirements.

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

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

Two tight sentences with the core action front-loaded and the default-marking behavior following directly. No filler.

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

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

Output schema exists so return values need not be explained, and annotations cover the safety profile. Still, for a create mutation with nested typed values and a low-coverage schema, the description leaves name constraints and value-shape expectations unaddressed.

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

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

Schema description coverage is only 33%: 'name' is undocumented and 'values' only carries a nested type description. The phrase 'initial set of variable values' gestures at what values means but adds no syntax, typing constraints, or name rules to compensate for the coverage gap.

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

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

States a specific verb (Create) and resource (environment) plus the initial payload it takes, which is clearer than the bare title. It does not, however, differentiate itself from siblings like update_environment or 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?

No when-to-use guidance, prerequisites, or alternative routing (e.g., update_environment for existing environments). The default-marking note is contextual but not a usage rule.

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

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

Goes well beyond the annotations: append-only immutability, idempotent re-post behavior ('posting the same text twice returns the row already written'), edit-permission requirement for description, non-overwrite of human-written descriptions, and attribution to Orchestra AI vs the API key.

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

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

Front-loads the core action, then groups parameter behavior into focused paragraphs; every sentence carries operational detail. Slightly dense in places but no filler.

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

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

An output schema exists so return values need not be explained, and the description still notes that the written event is returned. Combined with the mutation semantics and permission notes, an agent has everything needed to call it correctly.

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

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

Schema coverage is already 83% (baseline 3), and the description adds meaning the schema lacks — the ORCHESTRA_AGENT_SESSION_ID source, the required coupling of AI_DIAGNOSIS_* to agentSessionId, and the duplicate-suppression behavior on comment text.

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

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

States a specific verb and resource — 'Append a row to an incident's timeline, returning the event it wrote' — which is a narrow, well-scoped operation distinguishable from sibling mutations like update_incident or merge_incidents.

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

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

Gives explicit conditions for each eventType, including that the AI_DIAGNOSIS_* types require agentSessionId and that description is only accepted with COMPLETED/FAILED. It stops short of naming alternative tools or when not to comment at all, but the mode-selection guidance is clear.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: a left-out order places the monitor last so it only claims unclaimed events, and mute claims events without raising an incident or alert. It does not cover auth requirements (the account-id header) or duplicate-name behavior.

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

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

Front-loaded with the definition, then three sentences that each carry distinct information (match/groupBy/action mapping, the mute exception, the order default). No filler and every clause earns its place.

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

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

An output schema exists, so return values need not be explained. For a 9-parameter mutation tool with nested objects, the description covers the semantically hardest concepts well. Gaps are the account-scoping/auth requirement and the less central parameters (trigger, enabled, severity).

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

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

Schema description coverage is only 33%, so the description carries extra burden and partially meets it: it explains match, groupBy, action, the mute flag, and the order default with real meaning ('what makes two of them one incident'). However name, enabled, trigger, severity, assignee, and description are not addressed at all in the description.

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

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

States a specific verb and resource and then defines what a monitor actually is (a rule mapping failures to incidents). The distinction from update_monitor/reorder_monitors is implied by 'Create' plus the explanation of creation-time defaults like order. An agent can tell what this tool produces without opening the schema.

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

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

Usage is implied through semantics rather than stated: the match description explains the 'at least one dimension' requirement and the watch-out that an empty match would claim every event. But nothing says when to reach for create_monitor versus update_monitor, reorder_monitors, or list_monitors.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-not-destructive profile is covered by structured data. The description adds only that the body is; it says nothing about permissions, what 'published' vs draft implies, storage-provider side effects, or account scoping, leaving meaningful behavioral gaps.

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

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

Two short sentences, front-loaded with the action and followed by the one useful prerequisite. No filler and nothing buried.

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 11-parameter, nested-object mutation with only 18% schema coverage, the description is too thin; the output schema means return values need not be described, but the input-side gaps remain. An agent could not confidently populate the branch/repository/storage parameters from this definition alone.

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 18% across 11 parameters, so the schema does almost none of the work; the description must compensate and largely doesn't. It only clarifies the 'data' payload shape and points at validate_pipeline, leaving alias, message, yamlPath, published, repository, defaultBranch, workingBranch, messageIsCustom, and storageProvider unexplained in both places.

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

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

States a specific verb and resource ('Create a new pipeline') and adds that the body carries a JSON pipeline definition, so the agent knows exactly what it produces. It does not, however, disambiguate from close siblings such as import_pipeline, migrate_pipeline, or update_pipeline, which an agent might reasonably 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?

Gives a concrete conditional next-step: run validate_pipeline (linked as the schema-validation endpoint) first if you want to check the payload without saving. That is real routing guidance, but it only covers validation, not when to prefer create over import_pipeline/migrate_pipeline for an existing definition.

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

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

Beyond the readOnlyHint annotation, it discloses a retention limit (7 days), truncation caps on parameter values, log tail and artifact list, and — importantly — that the response self-reports which parts were cut. That is a strong, agent-relevant behavioral disclosure that annotations do not 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?

Front-loaded with purpose, then payload contents, then retention/truncation caveats, then a fallback pointer. Every clause carries information; no filler.

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

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

With an output schema present the description needn't enumerate return structure, yet it still summarizes what comes back, notes retention limits, truncation behavior, and alternative tools. Nothing an agent needs to call or interpret this correctly is missing.

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

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

Two parameters at 50% schema coverage. account_id is fully documented in the schema (including API-key vs OAuth scoping), and task_run_id is self-evident from its name, but the description adds nothing about either parameter. Baseline 3 for schema-heavy coverage is appropriate.

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

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

States a specific verb and resource ('Deep dive on one failed task run') and then enumerates the exact payload — status/messages, taskParameters, runParameters, upstream task statuses, log tail, artifact filenames. This clearly separates it from list_task_runs and get_pipeline_run_status.

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

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

Explicitly routes to the alternatives ('Use download_task_run_log or download_task_run_artifact when the tail is not enough') and states the eligibility window ('queryable for 7 days only'). When-to-use and when-not-to-use are both present.

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

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

Annotations only supply readOnlyHint=true; the description adds the genuinely non-obvious operational facts: the response is base64-encoded, capped at 3MiB per call, and larger files must be paginated with advancing byte ranges. That is exactly the kind of behavior an agent would otherwise get wrong.

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

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

Three tight sentences, front-loaded with purpose then the size constraint and the chunking recipe. No filler and nothing buried.

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 supplies the return format and size limit, which is what an agent needs to consume the result. Missing is any hint that filenames come from list_task_run_artifacts and any statement of behavior once the range exceeds the file length.

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

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

Schema description coverage is only 20% (account_id is the sole documented param), so the description has to carry weight: it explains range_header's format and gives a concrete example. The three required identifiers (pipeline_run_id, task_run_id, filename) get no explanation, though their names are largely self-describing, so this partially compensates rather than fully.

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 (Download) and resource (task run artifact file) and adds the return encoding (base64), which cleanly separates it from the sibling download_task_run_log without the agent needing to open a schema.

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

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

Gives clear conditional guidance for range_header: use chunks when the file exceeds 3MiB, with a concrete example range value. It does not, however, point at list_task_run_artifacts as the way to discover valid filenames, so the entry path 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?

readOnlyHint already marks this as a safe read, and the description adds meaningful behavior beyond that: base64 encoding of the payload and a hard 3MiB per-call content cap with a chunking workaround. It does not state whether the log must exist or what happens on an out-of-range request, but the disclosure is well above the annotations alone.

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

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

Two tight sentences: the core action plus return format first, then the size constraint and chunking mechanic. No filler, and the most decision-relevant constraint (3MiB cap) is front-loaded.

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

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

For a read-only download with no output schema, the description covers encoding, size limits, and paging, which is what an agent needs to call it correctly. The gap is provenance of the three required IDs and the distinction from the artifact/log-listing 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 coverage is only 20% (just account_id documented), so the description carries real burden and it does explain range_header semantics and syntax with the byte-range example. It says nothing about filename, task_run_id, or pipeline_run_id (three required IDs), leaving those entirely to inference.

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 ('Download a task run log file') plus the return encoding ('base64-encoded'), which is a genuine fact the agent needs. It does not, however, distinguish itself from near-neighbor siblings like download_task_run_artifact or list_task_run_logs, so the agent must infer the boundary.

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

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

It gives real operational guidance for the chunking case (3MiB ceiling, advance range_header each call with a concrete example), which is implied usage for large files. It offers no when-to-use guidance relative to list_task_run_logs or download_task_run_artifact, so the routing decision is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds nothing beyond that: no statement about not-found behavior, whether external IDs are resolved against a specific integration, or any rate/scope constraint. With annotations carrying the burden, this is thin.

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

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

A single front-loaded sentence with no filler; every clause carries information.

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

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

An output schema exists so return values need no explanation, and readOnlyHint covers safety. For a simple lookup tool this is largely sufficient, missing only error/not-found semantics that an agent might want before calling.

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

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

Schema description coverage is 100% and the account-scoping header is thoroughly documented in the schema itself. The description's mention of 'Orchestra asset ID or external ID' merely restates the asset_id schema description, adding no syntax or format detail. Baseline 3 applies.

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

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

States a specific verb (retrieve) and resource (a single asset), plus the two identifier forms accepted. The word 'single' implicitly distinguishes it from the sibling list_assets, 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?

Usage is implied: call it when you already have an asset ID. There is no explicit statement of when to prefer this over list_assets or what happens if the ID is unknown, so guidance is only inferable.

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

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

Annotations already declare readOnlyHint=true, and the description goes beyond them by disclosing that variable values are included in the response — meaningful for a tool that may expose secrets/config. It stops short of noting authorization or account-scoping behavior, but adds real value over the annotation.

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

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

A single front-loaded sentence with zero filler; the resource, identifier, and notable payload detail are all packed in without redundancy.

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

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

An output schema exists so return values need no explanation, and the read-only nature is covered by annotations. The description mentions variable values and the lookup key, which is sufficient for a simple single-fetch tool; only account-scoping nuance is left to 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 coverage is 50%: the X-Orchestra-Account-Id header is fully documented in the schema, but environment_id carries only a uuid4 format with no description. The phrase 'by its ID' confirms environment_id's role but adds no format or lookup detail beyond the schema.

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

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

States a specific verb (Fetch) and resource (a single environment) scoped by ID, which implicitly distinguishes it from list_environments. It is clear but never names the sibling it differs from, so an agent must infer the distinction itself.

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?

'By its ID' implies the precondition that an environment_id must be known, which is usable guidance, but there is no explicit when-to-use, when-not-to-use, or reference to list_environments for discovery. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds that the response eagerly includes merge relationships and related resources, which hints at payload weight, but it says nothing about authorization scope, mutation, or errors beyond what structured data provides.

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

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

A single front-loaded sentence with no filler; the resource and the notable contents of the response come first. Every clause earns its place.

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

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

With an output schema present and annotations covering the safety profile, the description need not explain return values, and it doesn't over-reach. It is nearly complete for a simple by-ID getter, losing a point only for the absence of any when-to-use framing relative to the large set of incident siblings.

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

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

Schema description coverage is 100% and both parameters (incident_id, X-Orchestra-Account-Id) are documented in the schema itself, including the account-scoping rules. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Fetch a single incident') and adds the shape of the payload (merge relationships, summary counts, related resources). The word 'single' implicitly distinguishes it from list_incidents, but it does not explicitly name or contrast any sibling 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?

Usage is only implied: an agent can infer this is the by-ID lookup for one incident versus list_incidents. There is no explicit statement of when to reach for this tool, no prerequisites, and no routing away from merge_incidents, list_incident_events, or update_incident.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral value beyond that by disclosing that the payload expires and that the tool returns 410 afterward, which an agent needs to interpret failures correctly. Auth/account semantics are handled in the schema rather than here.

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

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

Two sentences, zero filler, with the key scoping constraint front-loaded and the expiry caveat immediately after. Every clause earns its place.

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

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

An output schema exists, so return-value details need not be described, and the 410/expiry caveat covers the main edge case. Combined with the schema and annotations, an agent has what it needs to call this correctly.

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

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

Schema description coverage is 100%, including a detailed explanation of the account-override header, so the schema carries the parameter burden and the baseline is 3. The description's mention of externalEventPath adds context about which event id is valid but no syntax or format detail beyond the schema.

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

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

States a specific verb (fetch) and a precisely scoped resource (the raw JSON an external system sent for one incident timeline row). The qualifier 'a row whose externalEventPath is set' distinguishes it cleanly from the sibling list_incident_events, so the purpose is unambiguous.

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

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

The description tells the agent the precondition for calling it - the timeline row must have externalEventPath set - which is effective routing guidance. It does not explicitly name an alternative tool or state when not to use it, so it falls short of a 5.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds useful scoping context about the credential-resolved workspace, but it does not disclose authentication requirements, rate limits, or what kind of state is returned beyond the output schema. With annotations covering safety, this is adequate but not rich.

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

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

The description is a single, front-loaded sentence with no wasted words. It is efficient and easy to parse, though its brevity leaves some contextual gaps that could have been addressed without harming conciseness.

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

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

The output schema exists, so return values need not be explained, and the readOnlyHint annotation covers safety. However, the description does not provide usage guidance or help interpret the large integration enum, leaving gaps for an agent choosing among many sibling tools.

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

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

Schema description coverage is 50%, and the description does not compensate for the undocumented integration enum. It says only 'for the given integration,' which largely restates the required parameter, while the optional account parameter is already fully described in the schema. No additional syntax, format, or selection guidance is 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 states a specific verb and resource: fetching stored state for a given integration. It also scopes the operation to the workspace resolved by the credential, which helps distinguish it from generic listing tools. However, it does not explicitly differentiate itself from sibling tools such as list_integration_connections or get_pipeline_data.

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

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

There is no explicit when-to-use guidance, nor any mention of alternatives or prerequisites. The agent can infer this is a read operation for integration state, but the description does not explain when to choose this tool over siblings or what conditions make it appropriate.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. Beyond that the description adds almost nothing: it doesn't say whether it errors when the monitor is missing, whether the result is cached, or what 'definition' excludes (e.g. runtime status).

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

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

A single short, front-loaded sentence with no padding — efficient and easy to scan. It is arguably too terse for what it omits, but as a structure it wastes nothing.

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

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

With an output schema present, return values need not be explained, and the annotations plus full schema coverage carry most of the load. Still, for a lookup tool it says nothing about failure behavior or account-scoping implications beyond what the schema already states.

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

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

Schema description coverage is 100%, with monitor_id and the X-Orchestra-Account-Id scoping/credential semantics fully documented in the schema itself. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (fetch) and resource (a monitor's definition), and the word 'single' implicitly distinguishes it from the sibling list_monitors. It does not, however, name or explicitly contrast with any sibling 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?

No when-to-use guidance and no explicit alternative is named; the agent must infer from 'single' that list_monitors is the bulk counterpart. There are no prerequisites, exclusions, or conditions 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?

readOnlyHint=true already covers the safety profile, so the bar is lower, and the description contributes the mutually-exclusive selector constraint that the empty required list does not enforce. It still omits what happens when zero or conflicting selectors are supplied, and whether branch/commit/version can be combined, so it is not fully transparent.

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

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

Two tight sentences with the purpose front-loaded and no filler. The second sentence partly repeats parameter names already visible in the schema, which keeps it from being maximally economical.

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

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

With an output schema present, return values need no explanation, annotations cover read-only safety, and the schema fully documents parameters; the description adds the missing selector-exclusivity rule. It could still note the failure mode for an invalid selector set or point to the sibling used for data/runs retrieval.

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

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

Schema description coverage is 100% and each selector parameter is documented in the schema, including the repository/yaml_path pairing. The description restates the selector list and adds the exactly-one rule, but supplies no format or semantics beyond what the schema already carries, so the baseline 3 applies.

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

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

"Fetch a single pipeline" gives a specific verb and resource, and "single" implicitly contrasts with the sibling list_pipelines. It does not, however, distinguish itself from get_pipeline_data or pipeline_context, which an agent would have to disambiguate on its own.

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 the invocation rule (provide exactly one selector) and enumerates the valid selector combinations, which is real usage guidance. It gives no when-to-use vs when-not-to-use guidance relative to siblings like get_pipeline_data or list_pipelines, leaving selection 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?

readOnlyHint=true already declares this a safe read. The description adds that it returns the full definition and can pin to a specific revision, which is useful, but it says nothing about the git-backed vs versioned YAML distinction or the account-scoping behavior that the schema only hints at. Adequate but not rich.

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

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

Two tight sentences with the primary selector front-loaded and the optional revision path second. No filler, though the second sentence compresses several distinct selector types into one clause.

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

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

An output schema exists so return values need not be explained, and the schema fully documents the parameters. The description is complete for the core flow, with only minor gaps around the yaml_path/repository pair and account-override semantics, which the schema already covers.

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

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

Schema description coverage is 100%, so the schema already documents all eight selectors. The description repeats the primary ones (pipeline_id, alias, version, branch, commit) without adding format or mutual-exclusion rules, and omits yaml_path/repository pairing entirely. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch the full pipeline definition') and clarifies that selection is by pipeline_id or alias, with optional revision selectors. It partially distinguishes itself from siblings like get_pipeline by emphasizing the full definition plus revision loading, though it never names those siblings explicitly.

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

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

It explains how to select a pipeline and that version/branch/commit load a specific revision, which implies usage. But it gives no guidance on when to prefer this over get_pipeline, list_pipelines, or pipeline_context, and no prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to re-establish safety. It adds that the output is a lineage graph URL, but it does not disclose details like whether the pipeline run must exist or how the URL is formatted. With annotations in place, this is acceptable but minimal.

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

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

The description is a single, direct sentence with no filler. It front-loads the action and target, and every word 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?

This is a low-complexity, single-parameter, read-only tool with an output schema available. The description covers the core purpose sufficiently. The only notable gap is not explaining the provenance or format of pipeline_run_id, but the output schema and annotation coverage compensate for most of what an agent needs.

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

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

Schema description coverage is 0%, so the description carries responsibility for explaining the single parameter, pipeline_run_id. It does not mention where the ID comes from, what format it expects, or how it is used. The parameter name is self-explanatory, but the description still adds no parameter-level meaning.

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

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

The description uses a specific verb, 'Build', and a clear target, 'the URL of a pipeline run's lineage graph in the Orchestra UI.' This distinguishes it from sibling tools that retrieve statuses, logs, or artifacts, since none of them construct a UI URL.

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

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

The description gives no explicit guidance about when to use this tool versus alternatives like pipeline_context or get_pipeline_run_status. The intended use is implied, but there are no exclusions, prerequisites, or alternative tool mentions.

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

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

Annotations already declare readOnlyHint=true, and the description adds no behavioral context beyond that — no mention of what happens if the run ID is unknown, retention windows, or polling semantics. For a trivially safe read tool the annotations carry the safety profile, but the description contributes essentially nothing new.

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

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

A single sentence that states the purpose up front with no filler; the only extra element is a documentation link, which is cheap and potentially useful. Nothing needs trimming.

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

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

An output schema exists, so return values need not be described, and both parameters are covered by the schema with annotations covering the safety profile. What is missing is error/edge-case behavior (unknown run ID, permission failure) and how this relates to adjacent per-run tools.

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

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

Schema description coverage is 100%, with pipeline_run_id (uuid4) and X-Orchestra-Account-Id both fully documented in the schema, including the multi-account rules. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb (Retrieve) and a specific resource (status details for a single pipeline run), and the word 'single' implicitly separates it from list_pipeline_runs. It does not, however, differentiate against other per-run siblings such as get_pipeline_run_lineage_url or list_task_runs_for_pipeline_run.

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

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

There is no explicit when-to-use guidance, no prerequisites (e.g., the run must be complete vs. in-flight), and no exclusions or named alternatives. The only hint is the word 'single', which an agent must infer means 'use this instead of list_pipeline_runs'.

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

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

Annotations already establish readOnlyHint=false and destructiveHint=false, so the mutation nature is known. The description adds that the source is Git-backed, but says nothing about whether an existing pipeline is overwritten, what happens on conflict, which credential/account is required, or whether the import is synchronous.

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

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

A single tight sentence with the operation front-loaded and no filler. Nothing in it is wasted, though the terseness is also the source of the gaps elsewhere.

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

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

An output schema exists, so return values need not be explained, but for a 7-parameter mutation tool with 14% schema coverage the description is far too thin. It omits conflict/overwrite behavior, auth context, and the meaning of nearly all parameters.

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

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

Schema description coverage is only 14% (just X-Orchestra-Account-Id), leaving six parameters undocumented. The description only implies the 'repository' parameter via the phrase 'from a repository' and explains none of yamlPath, defaultBranch, workingBranch, storageProvider, or alias.

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 (Import) and resource (a Git-backed pipeline definition) with a clear source (a repository) and destination (Orchestra). It does not, however, differentiate itself from close siblings such as create_pipeline, migrate_pipeline, or validate_pipeline, which an agent must choose between.

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 says nothing about when to import rather than create or migrate a pipeline, and gives no prerequisites (e.g. repository access, credential setup). Usage must be inferred entirely from the name and the sibling list.

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

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

Annotations only declare readOnlyHint, so the description usefully adds that an API key yields exactly one workspace while an OAuth token yields the granted workspaces still matching the user's membership. It also names the downstream header mechanism (X-Orchestra-Account-Id), which is real behavioral context beyond the annotation.

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

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

Two short paragraphs, scoping behavior front-loaded ahead of the downstream usage note. Every sentence carries information and none is redundant.

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

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

An output schema exists, so return-value structure needn't be re-explained. Combined with the annotation and the credential-dependent scope plus follow-up usage guidance, an agent has everything needed to call and use this tool correctly.

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

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

There are zero input parameters, so the baseline is 4. The description adds meaningful semantic context by clarifying that a returned id is the selector used on workspace-scoped calls, tying the output back to how it is consumed.

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 ('Lists the workspaces this credential can act on') and precisely distinguishes how the result set varies by credential type (API key vs OAuth). No sibling tool lists accounts, and the scope is unambiguous.

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

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

It explains the when and why clearly through the credential-type behavior and tells the agent what to do with the result ('Pass a returned id to select the workspace...'). There is no explicit comparison to an alternative, though no analogous sibling exists to route away from.

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

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

Annotations only declare readOnlyHint=true, which the description does not contradict. Beyond that it adds useful behavior: results are paginated, scoped to the credential's workspace, and default-sorted by created_in_integration descending. It does not cover pagination limits or how the account-override header behaves, keeping it out of 5 territory.

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

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

Two sentences, front-loaded with what the tool returns before the filtering and sorting details. There is no filler or repetition of the title.

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

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

With an output schema present, the description need not explain return values, and the rich param schema covers inputs. It gives enough context on scope, filters, and default ordering to call the tool correctly, though it omits any note on pagination boundaries or the account-override parameter's semantics.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters including defaults, enums, and comma-separated multi-value syntax. The description's filter list merely mirrors the schema at a high level and adds no format or syntax detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Retrieve a paginated list of assets') plus the scope ('for the workspace the credential resolves to'). It is clearly a list operation distinct from get_asset_by_id, though it never names siblings explicitly, 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?

The description enumerates the dimensions you can filter by, which implies when to reach for this tool, but it gives no explicit when-to-use vs. when-not guidance and does not route the agent to alternatives such as get_asset_by_id for a single lookup.

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?

readOnlyHint=true already declares the safety profile, and the description adds useful context beyond it: results are workspace-scoped to the credential and returned newest-first, and the required timestamp establishes the read window rather than the query being open-ended. It does not mention pagination behavior or result volume, 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?

Two sentences, no filler. The scope and ordering lead, and the parameter-interaction rule follows in the second sentence where it is most actionable.

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

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

An output schema exists so return values need no explanation, and all nine parameters are schema-documented. The description supplies scope, ordering, and filter-window semantics, but omits any pointer to sibling tools or a note on how the credential/account-id header interacts with the workspace scoping it mentions.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by explaining the semantic relationship between parameters - occurred_after defines the window and all other filters narrow within it, i.e. conjunctive filtering - which an agent cannot infer from the per-field descriptions alone.

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 (list the audit trail) plus scope ('for the workspace the credential resolves to'), ordering ('newest first'), and payload content ('who did what, to which resource, and what changed'). An agent can distinguish this from siblings like list_incident_events 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?

Explains the mechanics of use: 'occurred_after' is required and sets the read window, while every other filter narrows within it. That is clear operating context, but the description never names an alternative tool or a when-not condition against siblings such as list_incident_events.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: what is returned (metadata only) and what is deliberately excluded (variable values), which is a real behavioral boundary an agent would otherwise discover only from a failed follow-up call.

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

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

Two sentences with zero filler, and the scope limitation is front-loaded before the pointer to the sibling tool. Every clause earns its place.

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

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

An output schema exists, so return values need no prose explanation, and the single parameter is fully covered by the schema. For a simple read-only list tool, 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 description coverage is 100% and the single optional parameter is fully documented in the schema itself, including the account-key vs OAuth-token semantics. The description adds nothing about the X-Orchestra-Account-Id override, so the baseline of 3 applies.

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

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

States a specific verb ('List') and resource ('environments') plus the scoping constraint ('for the workspace the credential resolves to'), which separates it from unqualified list tools. The second sentence explicitly contrasts it with the get_environment sibling, so an agent can route between the two without opening either schema.

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

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

The description tells the agent when to use this tool rather than get_environment: list for metadata, fetch by ID for variable values. It does not state exclusions (e.g., pagination limits or when listing is inappropriate), so it stops short of explicit when-not guidance.

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

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

Annotations only declare readOnlyHint=true; the description goes further by disclosing the sort order, that pagination starts from the beginning, and a genuinely useful scale warning that grouped incidents accumulate one event per attached failure and can reach hundreds of rows. That volume context is exactly what annotations cannot convey.

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

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

Two sentences, front-loaded with the core action and ordering. The second sentence is longer than strictly needed but earns its place by warning about row volume before an agent commits to fetching.

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

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

An output schema exists, so return values need not be explained. Combined with full schema coverage, the description supplies scope, ordering, pagination behavior, and volume context, leaving little an agent would need that isn't covered.

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

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

Schema description coverage is 100% and all four parameters are documented in the schema itself, so the baseline is 3. The description's mention of pagination and newest-first ordering adds only marginal semantic value beyond the documented page/page_size fields.

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 ('Fetch the timeline for a single incident') plus the ordering ('newest first'), so an agent can tell it apart from get_incident and list_incidents. It doesn't explicitly name a sibling it is not, which keeps it 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?

Usage is implied (inspect a single incident's history chronologically), but there is no explicit when-to-use versus get_incident or list_incidents, and no prerequisites or exclusions. Adequate but leaves routing to inference.

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

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

Annotations only declare readOnlyHint=true, but the description adds real behavioral traits: result ordering (most severe first), the merged-parent/child nesting structure, and the important constraint that children are always returned with their parent so filtering still yields a complete incident. This goes well beyond the safety hint.

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

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

Purpose is front-loaded in the first clause, followed by the scope/ordering details and then the filter caveat. Efficient with no filler, though the second sentence is dense and slightly repetitive about filtering.

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

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

An output schema exists, so return values need not be explained, and the description still covers the key structural nuance (nesting and filter scope). All parameters are schema-documented; the only gap is that it doesn't tie the tool to specific sibling workflows or note pagination behavior.

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

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

Schema description coverage is 100%, so all seven parameters are already documented. The description merely restates the `name` substring-match semantics already in the schema and says nothing extra about status, severity, paging, or include_archived, so it adds little beyond structured data.

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 (list incidents) plus scope (workspace the credential resolves to), ordering (most severe first), and merged-child nesting. This clearly distinguishes it from list_incident_events and get_incident, which operate on events and single incidents respectively.

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

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

Gives clear usage context: filters apply to top-level incidents only, and `name` supports case-insensitive substring matching. It does not name sibling alternatives (e.g. get_incident, list_incident_events) or state when-not-to-use, so it stops short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read, but the description adds genuine behavioral value: the result is scoped to the workspace the credential resolves to, and secret auth parameters are never returned. That return-content guarantee is not derivable from annotations or schema.

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

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

Three short sentences, front-loaded with the scope and resource, then the safety guarantee, then the filters. Each sentence carries information; no filler or restatement of the title.

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

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

With an output schema present the description need not explain return values, yet it still discloses the metadata-only guarantee. Workspace scoping and filtering are covered; the only gap is the absence of guidance on the account-override interaction, which the schema itself handles.

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

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

Schema description coverage is only 33%, with the two filter parameters carrying no schema-level prose. The description names integration and authStatus as filters, which is useful, but adds nothing about how multiple filters combine or what the enum values mean.

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 (list integration connections) scoped to the credential's workspace, which is clear and actionable. It does not explicitly contrast itself with siblings such as get_integration_state_for_state_aware or list_accounts, so an agent must infer the boundary.

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

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

The sentence 'Optionally filter by integration or authStatus' implies the intended usage context, but there is no explicit when-to-use vs. when-not guidance and no named alternative tool for related queries about integration state.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds genuinely useful behavior the annotation cannot convey: precedence when monitors claim the same event (lower `order` wins). It does not cover pagination or ordering guarantees beyond that, but the output schema exists to describe returns.

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

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

Two tight sentences with the primary purpose front-loaded and the tie-break rule following immediately. No filler or restatement of the title.

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

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

Annotations cover the safety profile and an output schema exists, so the description needn't explain returns. The evaluation-order/tie-break rule is the key semantic an agent needs for this list tool; only filtering or pagination behavior is left unstated.

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

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

There is one optional parameter (X-Orchestra-Account-Id) with 100% schema description coverage, so the schema fully documents account selection semantics. The description adds nothing about it, which is the correct baseline when the schema carries the load.

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

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

States a specific verb (list) and resource (monitors), plus the meaningful detail that results come in evaluation order. It reads clearly against siblings like get_monitor and reorder_monitors, though it never names them explicitly.

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

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

There is no explicit when-to-use guidance, no exclusions, and no mention of the related siblings (get_monitor, reorder_monitors, update_monitor) that an agent might confuse with this call. Usage is only implied by the verb 'list'.

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 readOnlyHint already declaring a safe read, the description adds substantial non-obvious behavior: the 24-hour default window, the 7-day maximum range per request, the 2023-01-01 floor on time_from, and a documented default change effective 2026-10-01. These are exactly the gotchas an agent could not infer from schema or annotations.

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

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

The purpose sentence is front-loaded and the note block is well-organized with the time-window rules grouped together. It is slightly long for the amount of information, but every clause (defaults, limits, migration date) 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 an output schema exists, return values need not be explained, and the description covers filtering, time-window constraints, credential/account scoping, and pagination. What remains unstated is result ordering and what an 'operation' entity represents, which is minor for a list tool with rich schema support.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema lacks: the interaction between time_from and time_to, the 7-day cap when both are passed, and the default 24-hour window when neither is. That is real added meaning beyond the field-level descriptions.

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

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

States a specific verb and resource ('Retrieve a paginated list of task operations') plus the scope ('the workspace the credential resolves to'). It is distinct from siblings like list_task_runs and list_pipeline_runs by naming 'operations', though it does not explicitly contrast itself with the nearest sibling.

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

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

Gives clear operational context: when to pass time_from/time_to, what happens when neither is provided, and which filters are available to narrow results. It does not say when to prefer this tool over alternatives such as list_task_runs, so it stops short of full 5-level 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?

The readOnlyHint annotation already covers the safety profile, so the description doesn't need to emphasize read-only behavior. It adds the detail that status accepts comma-separated values and enumerates them, but does not disclose other behavioral aspects like pagination defaults or sorting, which are left to the schema. This is adequate given the annotation.

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

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

The description is a single, front-loaded sentence that states the core action first and then provides the most critical parameter detail. There is no redundant wording, and every word 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 presence of a full output schema and comprehensive parameter descriptions in the input schema, the description is sufficient for an agent to understand the tool's purpose and key filter. It doesn't mention pagination or time windows, but those are documented in the schema. The only minor gap is lack of sibling differentiation, which is covered under usage guidelines.

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 covers all 9 parameters with descriptions, so the baseline is 3. The description adds specific value by enumerating the allowed status values (CREATED, RUNNING, SUCCEEDED, etc.), which the schema does not list. This extra semantic detail enhances parameter understanding beyond the schema.

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

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

The description states a specific verb ('List') and resource ('pipeline runs') and mentions optional filters, clearly distinguishing it from sibling tools like get_pipeline_run_status or cancel_pipeline_run. It lacks an explicit statement of the return type, but the title and phrasing are unambiguous.

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

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

The description gives no guidance on when to use this tool versus alternatives, such as get_pipeline_run_status for a single run or list_task_runs for tasks. It only describes the action without contextualizing selection criteria or exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: passing page/page_size changes the response shape (paginated envelope with page, page_size, total, results), results are sorted by pipeline name, and name matching is case-insensitive substring. That is meaningful disclosure of how the call behaves.

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

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

Three short sentences, front-loaded with the scope statement followed by the two operational tips. Little waste, though the pagination-field enumeration slightly overlaps with the output schema.

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

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

An output schema exists, so return values need not be re-explained; the description still adds the sorting and paging-shape behavior, which is enough for an agent to call it correctly. Nothing critical is missing, though an explicit pointer away from get_pipeline would round it out.

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

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

Schema description coverage is 100%, so every parameter including the account-id header is already documented in the schema. The description largely restates schema content (case-insensitive substring, pagination fields) with no extra syntax, defaults, or interaction notes, so the baseline 3 applies.

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

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

States a specific verb and resource (list pipelines) and adds a scope qualifier: the workspace the credential resolves to. It does not explicitly distinguish itself from siblings like get_pipeline or list_pipeline_runs, but the workspace/credential scoping is concrete enough for an agent to recognize it as the enumeration entry point.

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 prescriptive guidance on how to call the tool ('Always pass page and page_size') and how to narrow results with `name`, which is useful operational context. However, it never says when to choose this over alternatives such as get_pipeline for a single pipeline, so the when/when-not dimension 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?

The readOnlyHint annotation already establishes this is a safe read, so the bar is lower. The description adds useful domain context by naming which dbt artifacts appear, but says nothing about pagination, result limits, or what happens when a run produced no artifacts.

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

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

A single sentence with the core purpose front-loaded and the illustrative artifact list appended as concrete payoff. No filler and nothing redundant.

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

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

An output schema exists, so return values need not be explained, and the two required IDs are fully documented in the schema. For a simple list tool this is nearly sufficient; only the routing versus the download sibling is missing.

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

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

Schema description coverage is 100%, so task_run_id, pipeline_run_id, and the account-id header are all documented in the schema; the description adds no syntax or format detail beyond that. Baseline 3 applies when the schema does the heavy lifting.

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

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

Names a specific verb ('List') and resource ('artifacts linked to a task run') and concretely enumerates the artifact types (dbt manifest.json, run_results.json, catalog.json, sources.json). It does not explicitly distinguish itself from the sibling download_task_run_artifact, but the list-vs-download distinction is inferable from the verb.

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

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

The description gives no when-to-use guidance, no prerequisites, and never mentions the closely related sibling download_task_run_artifact (which fetches a single artifact) or list_task_run_logs. The agent must infer the choice from tool names alone.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds a small amount of behavioral value by disclosing that the result is a set of filenames rather than log content, but it says nothing about pagination, filtering, ordering, or behavior when a run has no logs. Adequate but thin against the annotation baseline.

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

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

Two short sentences, zero filler, with the core action front-loaded and the follow-up workflow hint second. Every sentence earns its place.

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

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

An output schema exists, so return-value explanation is not required, and the description covers the purpose plus the next step in the workflow. It is close to complete for a simple read-only list tool, with only minor gaps (no mention of empty results or ordering).

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

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

Schema description coverage is 100%, so task_run_id, pipeline_run_id, and the account-override header are already fully documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List log files linked to a task run'), which is enough to distinguish it from the neighboring list_task_run_artifacts tool. It does not explicitly name that sibling, but the 'log files' scoping is clear.

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

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

The second sentence gives actionable chaining guidance: the returned filenames are meant to be fed to the download endpoint (download_task_run_log). It gives clear context for what to do with the result, though it does not state when this tool should be preferred over siblings or any prerequisites/exclusions.

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

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

Annotations declare readOnlyHint=true, so safety profile is clear. The description adds non-obvious operational context beyond the schema: the 24-hour default window, the 7-day max range, the 2023-01-01 floor, and especially the 2026-10-01 default change from 7 days to 24 hours. These are the kind of behavioral traits an agent can't derive from structured fields.

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

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

Front-loaded with purpose and scope, then a clearly delineated Note for time-window rules and a final example of multi-value filtering. Well-structured; slightly long, but each block carries distinct information.

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

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

Given an output schema exists (so return shape need not be explained) and annotations cover the read-only safety profile, the description fills the remaining gaps: default time window, historical default change, max range, and multi-value filter syntax. An agent has enough to call it correctly.

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

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

Schema description coverage is already 100%, and the schema documents page_size, include_superseded, time bounds, and ID filters fully. The description adds the comma-separated multi-value semantics for status and integration (useful, since the schema only says 'where the parameter accepts multiple values'), but otherwise mostly restates schema-defined behavior. Baseline 3 is appropriate given the schema already carries the load.

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

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

The description states a specific verb and resource ('retrieve a paginated list of task runs') and scopes it to the workspace the credential resolves to. It does not explicitly contrast itself with the sibling 'list_task_runs_for_pipeline_run', so a reader must infer the distinction from context.

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

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

The description clearly explains when default behavior applies (last 24 hours if no time range is given), the 7-day maximum window when both bounds are set, and the explicit recommendation to pass time_from/time_to to control the window. It does not, however, name when to use this tool instead of the pipeline-run-scoped variant.

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

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

The readOnlyHint annotation already establishes this is a safe read, lowering the disclosure burden. The description's pagination statement (default 10, max 50) largely repeats the page_size schema description rather than adding new behavioral context like ordering or total-count semantics.

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

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

Two tight sentences with the core purpose front-loaded and no filler. The second sentence is somewhat redundant with the schema's page_size description, slightly diminishing its 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?

With an output schema covering return shape, read-only annotations, and full parameter documentation, the definition is complete enough to call the tool correctly. It only lacks sibling routing guidance for choosing between this and list_task_runs.

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

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

Schema description coverage is 100%, so all five parameters, including the non-obvious include_superseded flag and the X-Orchestra-Account-Id header, are already documented in the schema. The description only echoes page_size defaults, adding nothing beyond structured fields, so the baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (task runs) scoped to 'a single pipeline run', which separates it by scope from the sibling list_task_runs. It stops short of naming an alternative explicitly, so it is clear but not maximally differentiating.

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

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

The phrase 'belonging to a single pipeline run' implies when this tool applies versus a broad listing, but there is no explicit when-to-use, when-not-to-use, or named alternative such as list_task_runs. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: merging is one level deep and certain merges are rejected rather than nested. It stops short of noting that the operation is reversible via unmerge, which would matter for 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?

Two sentences, front-loaded with the core action and followed by the nesting constraint. No filler, though the second sentence is somewhat dense.

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

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

An output schema exists, so return values need not be explained, and the description covers the tricky semantic (non-nesting merge) plus the account fallback is documented in the schema. The only real gap is the absence of any pointer to unmerge_incidents as the inverse/recovery path.

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

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

Schema coverage is 67%: incident_id and X-Orchestra-Account-Id carry descriptions, while incidentIds does not. The description frames the array as 'the incidents named in the request body,' implying plurality, but adds no format/count details (e.g., the max of 5) beyond the schema. Baseline 3 fits since the schema does most of the work.

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

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

The description gives a specific verb+resource ('merge the incidents ... into the incident in the path') and clarifies the source/target roles, so the agent can tell it apart from update_incident or list_incidents. However, it never names the most confusable sibling, unmerge_incidents, which would have sharpened the distinction.

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

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

It states the operational constraint (one-level-deep merging; rejections for nesting) but gives no explicit guidance on when to prefer this over sibling operations such as unmerge_incidents or update_incident. Usage is implied by the merge semantics rather than stated.

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

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

Annotations only tell the agent readOnlyHint=false and destructiveHint=false. The description adds no behavioral context beyond the intent: it does not say whether the migration is reversible, whether the pipeline is unavailable while migrating, what happens to existing content, or what permissions/credentials are needed for the target repository.

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

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

Two tight sentences with the core action front-loaded and the parameter exceptions trailing. No filler or repetition.

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

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

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. However, for an 8-parameter mutation with only 38% schema coverage, the description omits prerequisites, credential requirements for the target repository, and the effect of the migration.

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 low (38%), so the description needs to compensate. It clarifies the selector parameters (pipeline_id/alias) and one non-obvious rule for working_branch vs default_branch, but leaves repository, path, storageProvider, and defaultBranch semantics unexplained.

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 (migrate) and resource (pipeline) plus the direction of the change: Orchestra-backed storage to git-backed storage. This clearly separates it from update_pipeline or create_pipeline, though it does not name a sibling explicitly.

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

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

The description gives operational guidance on identifying the target ('pipeline_id or alias') and a conditional rule ('omit working_branch when it equals default_branch'), which is real usage help. It does not say when to choose this tool over update_pipeline or the other pipeline-mutating siblings.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: idempotent no-op behavior on repeat calls and a clear temporal boundary (until the account's alert budget next refills). It does not mention auth/permission nuances, but the schema already documents the account-override semantics.

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

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

Two short sentences, front-loaded with the core action and effect, with zero filler. Every clause (duration, idempotency) 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?

An output schema exists, so return values needn't be explained, and both parameters are fully documented in the schema. For a simple mute mutation the description is nearly complete, with the only gap being no explicit routing to the mute/unmute/update incident siblings.

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

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

Schema description coverage is 100%, including an in-depth explanation of the X-Orchestra-Account-Id override, so the schema carries the parameter burden. The description adds nothing about either parameter, which is acceptable given full coverage but leaves no incremental value; baseline 3 applies.

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

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

States a specific verb and resource ('Silence further alerts on this incident'), which is clearly a mute action rather than a generic update. It adds the temporal scope (until the alert budget refills) that disambiguates from a permanent change, though it never names the obvious counterpart unmute_incident to sharpen distinction.

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

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

The description gives no guidance on when to choose this over siblings such as update_incident, merge_incidents, or unmute_incident. The only usage-relevant statement is the idempotency note ('Already muted is a no-op'), which is behavioral rather than a when-to-use routing hint.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds genuinely useful behavioral context beyond that: exactly what a paused state suppresses (schedules, sensors, trigger events, start_pipeline calls), confirming pausing is non-destructive and reversible. It omits any note on permissions or the effect on already-running runs.

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

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

Two tight sentences: the action and identifier first, then the behavioral consequence. No filler and everything front-loaded.

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

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

An output schema exists, so return values need not be described, and the effect of pausing is well covered. The main gap is that the bidirectional behavior of the `paused` flag is left for the agent to infer from the parameter name.

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

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

Schema coverage is 67% and the schema already documents pipeline_id_or_alias and the account-id header. The description restates the alias/ID acceptance but adds no format or validation detail, and never explains the `paused` boolean semantics (true=pause, false=unpause). Baseline 3 is appropriate.

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

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

States a specific verb pair (pause/unpause) and resource (pipeline) and the identifier it accepts. It is clearly distinguishable from siblings like start_pipeline or cancel_pipeline_run, which involve different operations on the same 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?

The description implies when this operation is relevant by explaining what pausing does, but it gives no explicit when-to-use guidance, no exclusions, and does not name alternatives (e.g., cancel_pipeline_run for stopping in-flight runs). Usage must be inferred.

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

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

Annotations only declare readOnlyHint=true, so the description adds meaningful behavioral detail: it discloses the return payload (metadata, YAML as JSON, integrations, run outcomes, median duration) and the data freshness limit (last 7 days, the widest window the API serves). It does not cover auth requirements beyond the schema's account_id note or failure behavior, but the added scope and window information is substantive.

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

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

Three tight sentences, front-loaded with the purpose and contents, then the parameter form, then the run-window constraint. Every sentence adds information without filler.

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

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

An output schema exists, so the description need not explain return structure, and it sufficiently covers what is returned, the accepted identifier form, and the run history window. Minor gaps remain around run-count limits or error behavior, but the definition is complete enough for correct invocation.

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

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

Schema coverage is 50%: account_id is fully documented in the schema, but the required pipeline_id_or_alias has no schema description. The description compensates by stating 'Takes a pipeline ID or an alias,' which adds the alias option beyond the bare string type.

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

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

The description names the resource (a pipeline) and enumerates exactly what the tool returns: metadata, full definition as JSON, integrations, recent run outcomes, and median succeeded-run duration. This composite scope clearly distinguishes it from siblings like get_pipeline or get_pipeline_data, which cover only subsets.

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?

'What an agent needs before editing or reasoning about a pipeline' gives explicit usage context. However, it does not name alternatives or state when not to use this tool versus get_pipeline, get_pipeline_data, or list_pipeline_runs.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact – that this is a full-list replacement where every monitor must appear exactly once – but does not say what happens to ordering-dependent behavior (e.g., active alerts or in-flight evaluations) after reordering.

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

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

Two tight sentences with the core action front-loaded and the call constraint immediately after. No filler or redundancy.

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

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

An output schema exists, so return values need not be described. For a mutation tool whose annotations carry the safety profile, the description supplies the essential calling contract (full-list, exactly-once) plus account scoping via the schema. Nothing critical is missing.

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

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

Schema coverage is 50%: X-Orchestra-Account-Id is fully documented in the schema, but monitorIds (array of uuid4) has no schema description. The description compensates by explaining the array's semantics – it must contain every monitor exactly once and its index becomes each monitor's order position.

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

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

The description names a specific verb and resource ('Set the evaluation order of the workspace's monitors'), which clearly separates it from sibling mutations like update_monitor (field edits) and reads like list_monitors. It stops short of explicitly naming an alternative sibling, so it is clear but not fully differentiated.

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

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

Usage is implied rather than stated: the reader infers this is for bulk reordering rather than editing a single monitor. The 'must name every monitor exactly once' constraint is a real precondition, but there is no explicit when-to-use/when-not guidance or mention of alternatives such as update_monitor.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds that all body fields are optional and that the response carries a pipelineRunId for polling, which is useful, but it omits auth/scope behavior, idempotency, and side effects of an actual run.

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

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

Three sentences, front-loaded with purpose, then field guidance, then the response contract. Every sentence adds value and there is no filler, though the field-routing sentence is dense.

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

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

An output schema exists, so return values need not be detailed, and the description appropriately limits itself to noting pipelineRunId for polling. For a 3-parameter trigger tool with a nested body, the routing guidance is sufficient, but several body fields and any precondition on pipeline state remain 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?

With 67% schema coverage, the description compensates by explaining the semantics of the key optional groups: branch/commit for Git-backed pipelines, versionNumber for Orchestra-backed published versions, and runInputs for pipeline input values. It leaves ciRunId, taskIds, retryFromFailed, environment, and environmentOverrides unexplained, so it is helpful but not exhaustive.

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 ("Start a pipeline run") and identifies the two ways the pipeline can be addressed, which cleanly separates it from siblings like cancel_pipeline_run, validate_pipeline, and update_pipeline. It does not explicitly name a sibling, 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?

Usage is implied by the field-routing guidance (branch/commit for Git-backed, versionNumber for published versions, runInputs for inputs), which tells the agent how to invoke it. However, it never says when to prefer this tool over alternatives or what preconditions exist (e.g., pipeline must be unpaused), so guidance is incomplete.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, indicating a non-destructive mutation. The description adds that incidents become standalone, which is useful behavioral context. However, it does not state whether the operation requires specific permissions, what happens if an incident is not part of the given incident_id, or any rate limits, leaving 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?

Two tight sentences that front-load the action and scope, with the inverse-of-merge statement adding efficient orientation. No wasted words.

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

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

With an output schema present, return values need not be explained. However, for a mutation tool with partial schema coverage and no explicit usage guidance or permission details, the description is minimal but sufficient to call the tool correctly, though it could do more to clarify constraints and outcomes.

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

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

Schema coverage is 67%, with incident_id and X-Orchestra-Account-Id documented in the schema. The description adds the concept of detaching from a path incident and restoring targets as standalone, but does not clarify the relationship between incidentIds (targets) and incident_id beyond what the schema already indicates, nor does it compensate for the undocumented incidentIds parameter.

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 (detach) and resource (incidents named in body from incident in path) and clarifies the effect (restore as standalone). It does not explicitly name the sibling merge_incidents, though 'The exact inverse of merge' implicitly references it, which provides some sibling linkage but not by name.

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

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

Usage is implied by the inverse-of-merge framing, which helps an agent understand the operation. However, there is no explicit when-to-use context, no exclusions, and the alternative merge_incidents is not named. Adequate but with clear routing gaps.

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

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

Annotations declare non-read-only/non-destructive, and the description adds genuine value beyond them by disclosing idempotent behavior ('A no-op if it was never muted, or already lapsed'), which tells the agent not to fear redundant calls. It stops short of naming auth/permission constraints, so not a 5.

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

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

Two tight sentences, zero filler, with the core action and the idempotency caveat front-loaded. Every clause earns its place.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. Combined with the idempotency note, the description is nearly complete for this simple, single-required-param mutation, missing only usage routing against siblings.

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

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

Schema description coverage is 100%, so the schema already fully documents incident_id and the account-override header. The description adds no parameter-level detail, which is the correct baseline when the schema does the heavy lifting.

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

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

The description states a specific verb+resource ('Lift this incident's mute early'), making the operation unmistakable and clearly differentiating it from the sibling mute_incident. An agent can tell instantly what this does.

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

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

Usage is implied by the semantics rather than stated: the no-op behavior tells the agent it is safe to call regardless of mute state, but the description never says when to prefer this over update_incident or other incident mutations. Adequate but with a clear gap.

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

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

Annotations declare it is a non-read-only, non-destructive mutation, and the description adds genuinely non-obvious behavior beyond that: values are replaced wholesale rather than merged, and setting the default unsets the prior default. It does not discuss permissions, error behavior, or reversibility, so it falls 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?

Three tight sentences, front-loaded with the operation scope before the edge-case semantics. No filler, no repetition of the title, and each sentence adds a distinct fact.

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

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

An output schema exists so return values need no explanation, and annotations already convey the safety profile; the description supplies the mutation semantics an agent needs. Minor gaps remain around null handling for `name` and the account-id header, but nothing critical is missing for a correct call.

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

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

Schema description coverage is only 20%, so the description must carry the load, and it does the most important part: it explains the replace-vs-merge semantics of `values` and the side effect of `defaultEnv`, which the schema cannot express. It leaves environment_id and the account-id header undocumented, so it does not fully 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 ('Update') and resource ('an environment') and enumerates the mutable fields: name, default flag, and variable values. It is clearly distinguishable from create/get/list_environment siblings by implication, though it never names an alternative explicitly.

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

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

The clause 'Only the fields supplied are changed; omitted fields are left untouched' implicitly tells the agent when this tool is appropriate (partial edits) versus create_environment, but there is no explicit when-to-use/when-not-to-use statement or prerequisite guidance.

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