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

With no annotations, the description carries full disclosure and does so richly: exact files written, output contracts for task vs SLI, a server-side rejection rule (identical task+SLI content), and two behavioral footguns (bash trailing main "$@" causing FD 3 errors; secret_vars injected as file paths rather than values). This is the kind of context an agent cannot get from the schema.

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

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

Long, but front-loaded with the purpose and organized into scannable sections, tables, and bullets that each carry load for a 35-parameter tool. Some prose (e.g. repeated SLI-variant explanations) could be tightened, but the density is largely justified by the operation's complexity.

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

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

Given a 35-param mutation tool with no annotations and an output schema (so return values need not be explained), the description is complete: it covers prerequisites, variant selection, dual-commit recipes, output contracts, and runtime footguns, leaving no obvious gap an agent would need 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 100%, so the schema baseline is 3, but the description adds real meaning beyond it: the script-source matrix (size/density/mode trade-offs), the runtime_vars vs env_vars vs secret_vars distinction, and which variants are stdio-only. It stops short of documenting a few params directly (branch, owners, interval_seconds), leaving that to the schema.

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

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

States a specific verb+resource ('Commit a tested script as an SLX to the workspace Git repo') and clarifies what gets written (slx.yaml + runbook.yaml/sli.yaml). Clearly distinguishes itself from commit siblings like run_script and deploy_registry_codebundle, whose relationship is spelled out.

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

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

Explicit prerequisites ('script should already be tested via run_script or run_script_and_wait'), a decision matrix mapping each script-source variant to a use case and mode, an alternative path for large scripts (registry codebundle + deploy_registry_codebundle), and two named recipes for committing task+SLI together.

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

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

With no annotations, the description carries the full burden and does the important part: it flags this is an UPSERT where a repeat call with an existing short_name REPLACES the entire configuration and resets omitted fields to defaults — a critical destructive behavior that no structured field conveys. It omits permission/auth requirements and any failure modes, but the key mutation semantics are disclosed.

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

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

Front-loaded with the core action, then procedurally organized (definition, follow-up calls, UPSERT warning). The persona explanation and skill pointer take space but each earns it; only the example persona sentence is slightly expendable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 13-parameter creation tool with an output schema, the description covers the essentials an agent needs: what is being created, the identity linkage to workspace_chat, the setup follow-ups, and the dangerous upsert semantics. Return values are covered by the output schema, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by linking short_name to the persona_name consumed by workspace_chat and distinguishing it from display_name. Advanced params like run_config, search_filters, and filter_* are left to the schema.

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

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

The first sentence gives a specific verb+resource (create a new AI assistant/persona in a workspace) and then explains what an assistant actually is, so the agent knows the domain concept without opening the schema. It also explicitly differentiates itself from the sibling update_assistant.

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

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

It names the alternative ('To change a few fields on an existing assistant, use update_assistant'), points at the full setup workflow skill, and describes the follow-up sequence (create_chat_rule / create_chat_command with scope_type='persona'). When to use, when not to, and what to do next are all explicit.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the scheduled-run behavior and its dependency set (cron fires → results delivered to each sink), which is genuinely useful. It stops short of permissions/authorization requirements, what happens on name collision, or side effects, so the mutation semantics remain only partially 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?

Front-loaded with the core action and naming rule, then the skill reference, then the scheduling clause. The final sentence largely duplicates the cron_schedule parameter description, so it is slightly redundant but still tight overall.

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

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

For a 14-parameter create tool with an output schema available, the description covers the primary workflow, the naming rule, and the scheduled-run path, and it routes to a skill for deeper scoping/scheduling detail. Missing only permissions and error/collision behavior, which keeps it from a 5.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters in detail. The description restates the cron_schedule dependency chain rather than adding format or edge-case detail beyond the schema (e.g., valid cron dialect, sink config shape). Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb (Create) and resource (chat command / slash-command), and the naming constraint plus the invocation syntax [/label](cmd://name) make it unmistakable. The verb alone cleanly distinguishes it from sibling CRUD tools (get_chat_command, update_chat_command, list_chat_commands, delete-style operations).

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

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

It gives one concrete usage conditional ("To run a command on a schedule, set cron_schedule plus sink_configs, run_as_user, and assistant_name") and points to a skill for scoping/scheduling/sinks. However, it never says when to prefer this over siblings like update_chat_command, nor any prerequisites (permissions, existing scope) for creation.

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

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

No annotations exist, so the description carries the full behavioral burden, yet it only says it uses an internal API. It is silent on required permissions, whether creation is idempotent, and any side effects. The skill reference is the only behavioral clue, and it is not elaborated.

Agents need to know what a tool does to the 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 with the action front-loaded and zero filler. It is efficient, though arguably terse given the tool's 6 parameters and lack of annotations.

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

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

An output schema and full parameter coverage handle returns and inputs, but for a create/mutation tool with no annotations the description should disclose auth requirements and side effects. It leaves the agent without the behavioral context needed to invoke safely.

Complex tools with many parameters or behaviors need more documentation. 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 is already documented in the schema, establishing a baseline of 3. The description adds no syntax, format, or relational detail beyond that, so it neither compensates nor detracts.

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

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

States a specific verb+resource combination ('Create a chat rule') that an agent can grasp immediately, and the AgentFarm API note localizes it. However, it does nothing to distinguish itself from the sibling create_chat_command or explain why one creates a rule versus updates one via update_chat_rule.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternatives. The pointer to 'runwhen-skill://manage-rules (scoping + wording guidance)' hints at supporting context but does not tell the agent when this tool is the right choice versus update_chat_rule or create_chat_command.

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

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

With no annotations, the description carries the full burden. It usefully discloses a post-creation side effect: articles are indexed into the Knowledge Overlay Graph and become searchable by the workspace AI assistant and other tools. It omits permission/auth requirements, duplicate-title handling, and what happens to existing content, leaving meaningful gaps for a mutation tool.

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

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

The purpose is front-loaded in the first sentence, followed by the skill reference, indexing behavior, and content guidance. Reasonably sized with little waste, though the inline 'Skill:' reference is slightly cryptic without further context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 description covers purpose, indexing effect, and content expectations for an unannotated create tool. Residual gaps are the missing permission/auth and duplicate-handling behavior, which a mutation tool would ideally state.

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

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

Schema coverage is 100%, and the schema already documents every parameter in detail (including the title recommendation and char limits), so the baseline is 3. The description adds content-topic examples but no field-level semantics beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain 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 Knowledge Base article') with the scope ('in a workspace'), which is clearly distinguishable from update/delete/get siblings. It stops short of naming the alternative create/update/delete tools or when each applies, 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?

The description offers content guidance ('architecture notes, troubleshooting guides, runbook context') and references a skill for scoping/lifecycle, which implies usage. However it never says when to create vs use update_knowledge_base_article or when creation is inappropriate, so the when/when-not routing 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?

With no annotations, the description carries the full disclosure burden and does so unusually well for a mutation: it reveals the operation is a soft-delete (recoverable/not a hard purge) and that attached persona-scoped rules and commands are NOT cascade-deleted. It omits auth/permission requirements and whether confirmation is needed, which keeps it below 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, zero filler, with the destructive/soft-delete nature front-loaded and the non-cascading caveat immediately after. Every clause carries information an agent needs.

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

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

An output schema exists, so return values need not be explained, and the two required params are fully covered by the schema. The description supplies the two most important behavioral facts (soft-delete, no cascade) for a low-complexity deletion tool; only permission/auth context 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% for both parameters, so the schema already documents workspace_name and assistant_name (including the optional workspace prefix). The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Delete (soft-delete) an AI assistant (persona)') and scopes it to a workspace, which cleanly separates it from create_assistant and update_assistant. It does not explicitly name any sibling or contrast behavior, so it stops just short of full differentiation.

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

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

Usage is only implied by 'if no longer needed', with no explicit statement of when to prefer this over update_assistant or how to handle the case where the assistant is still referenced. It does at least flag the follow-up cleanup of persona-scoped rules and commands, which is genuine usage-relevant context.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that deletion cascades to the Knowledge Overlay Graph index, a non-obvious side effect, but omits irreversibility, permission requirements, and whether a confirmation or soft-delete occurs.

Agents need to know what a tool does to the 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 immediately followed by the scope of the effect. No filler text.

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

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

For a two-param destructive tool with full schema coverage and an output schema, the description is nearly sufficient, especially since it explains the index side effect. It stops short of confirming irreversibility or auth needs, which matters for a delete operation with no annotations.

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

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

Schema description coverage is 100%, documenting both note_id (UUID of the article) and workspace_name (e.g. 't-oncall'), so the schema does the heavy lifting. The description adds no parameter-level meaning beyond that, which is the expected baseline here.

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

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

The description states a specific verb (Delete) and resource (Knowledge Base article) and adds the scope of removal via the Knowledge Overlay Graph index. Siblings like create_knowledge_base_article and update_knowledge_base_article are implicitly distinguished by verb, though the description 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?

It states what deletion does but gives no when-to-use guidance, no prerequisites, and no pointer to alternatives (e.g. use update_knowledge_base_article to modify rather than delete). The agent must infer usage from the name alone.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that this is a SOFT delete (tombstone via deleted_by/deleted_at), that a reconcile loop cleans up runbook and SLI rows, and that behavior matches the UI endpoint. It omits permission/auth requirements and whether the tombstone can be reversed.

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

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

The core action is front-loaded in the first sentence and the paragraphs are logically ordered (endpoint, mechanism, scope, migration). There is mild redundancy, since tombstoning and workspace-global scope are restated in the third paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 soft-delete mutation with no annotations, the description covers mechanism, side effects, and scope, and an output schema exists so return values need not be explained. It would be fully complete with a note on required permissions (or that none beyond workspace access are needed).

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

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

Schema coverage is 100%, so the two parameters are already documented and baseline would be 3. The description adds meaning beyond the schema by stating that branch and commit_message have been removed, which head off a caller passing obsolete arguments.

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

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

The first sentence gives a precise verb+resource+scope ('Soft-delete an SLX from the workspace via the v4 short-name endpoint'), and the endpoint is spelled out. The note that deletion is workspace-global and not Git-branch-scoped implicitly separates it from Git-oriented siblings like commit_slx.

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

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

It gives clear context for use (soft delete, workspace-global scope) and a migration caveat telling prior Git-path callers to drop branch/commit_message. It stops short of naming a sibling alternative or an explicit 'use this when / not when' rule, so it is clear context without exclusions.

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

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

With no annotations, the description carries the full burden. It usefully discloses the deployment mechanism (runbook.robot/sli.robot live in the codebundle's git repo, no inline script), which is non-obvious context beyond the schema. However, it omits key behavioral traits for a mutating deployment tool: required permissions, whether the deploy commits to workspace config, and side effects of the deploy_runbook/deploy_sli toggles.

Agents need to know what a tool does to the 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, front-loaded paragraphs with zero filler: purpose first, differentiation second, workflow third. Every sentence earns its place.

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

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

For a complex 23-parameter mutation with an output schema available, the description covers purpose, the sibling distinction, and the discovery workflow adequately, and need not explain return values. It stops short of describing deployment side effects, which matters given the absence of annotations.

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

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

Schema description coverage is 100%, so all 23 parameters are already self-documenting. The description adds no per-parameter meaning beyond pointing the agent to the registry as the source of values, 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+resource ('Deploy a registry codebundle as an SLX to a workspace') and explicitly distinguishes itself from the sibling commit_slx by contrasting the deployment mechanism (pre-built codecollection repo vs inline Tool Builder scripts). An agent can select this tool over commit_slx without opening either schema.

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

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

It names the alternative ('Unlike commit_slx...'), states the distinguishing condition, and provides a concrete pre-call workflow: 'Use search_registry + get_registry_codebundle to find the right codebundle, then call this tool with the values from the registry.' This is explicit when-to-use and how-to-source-inputs guidance.

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

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

With no annotations, the description carries the full behavioral burden. 'Get' implies a read, and 'full config' hints that the complete configuration is returned, but it says nothing about required permissions, error behavior for unknown assistants, or rate limits. This is thin for an un-annotated 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?

A single tightly constructed sentence with the action, resource, lookup key, and return depth front-loaded. There is 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 described, and the schema fully documents both parameters. The description is adequate for a simple two-parameter read tool but omits any usage routing or behavioral context that an agent would need when weighing this against its many 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%, with both assistant_name and workspace_name documented, so the baseline is 3. The description's 'short name' wording mirrors the schema's documented example format and adds no new syntax or format detail beyond it.

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

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

States a specific verb (Get) and resource (a single AI assistant/persona) and clarifies the lookup key (short name) plus the depth of the return (full config). It implicitly distinguishes itself from list_assistants by specifying 'a single', but never names 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?

There is no explicit when-to-use guidance, no mention of prerequisites, and no named alternative. The 'by its short name' phrasing weakly implies a lookup-when-you-know-the-name pattern, but nothing tells the agent when to choose this over list_assistants or get_workspace_context.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only adds '(full content)'. It says nothing about read-only safety, workspace scoping requirements, permissions, or error behavior when an ID is absent.

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

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

A single front-loaded sentence with no filler; the key scoping information appears before the parenthetical detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 fully documented in the schema. Only the absence of any behavioral/permission context keeps this from being complete.

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

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

Schema description coverage is 100%, so both command_id and workspace_name are already documented in the schema. The description adds no format or constraint detail beyond that baseline.

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

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

States a specific verb (get), a specific resource (chat command), and scoping (single, by ID) plus a cue about response depth ('full content'). This differentiates it from list_chat_commands, though it doesn't name that sibling explicitly.

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

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

Usage is only implied: retrieve by ID when the full command content is needed, versus a listing. No explicit when-to-use/when-not or named alternative such as list_chat_commands is given.

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

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

No annotations are provided, so the description carries the burden. It adds one useful behavioral detail ('full content'), distinguishing the response from a summary, but says nothing about permissions, rate limits, or error behavior for a missing/unknown rule_id.

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

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

A single short sentence with zero waste, front-loading the resource and its scoping qualifier. Nothing could be removed without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 both required parameters are fully documented in the schema. For a simple two-parameter read tool this is nearly complete; only auth/permission context is absent.

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

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

Schema description coverage is 100% – both rule_id and workspace_name are documented in the schema, including an example workspace value. The description adds nothing beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (Get), resource (chat rule), and scope (single, by ID), and adds that it returns full content. This distinguishes it implicitly from list_chat_rules, though it never names that sibling explicitly.

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

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

Usage is only implied by the word 'single' – an agent can infer this is for fetching one known rule versus listing many. There is no explicit when-to-use guidance, no mention of prerequisites, and no routing to list_chat_rules or update_chat_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?

No annotations are provided, so the description carries the burden. It discloses the return shape ('structured JSON') and the precondition of already having an issue ID, but says nothing about permissions, error behavior, or freshness of the data. For a low-risk read lookup this is adequate but 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?

Two short, front-loaded parts: the capability statement first, then the routing note. Every sentence carries information an agent needs and nothing is padded.

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

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

With both parameters fully documented, an output schema present to describe return values, and explicit routing against the nearest competing tool, an agent has everything required to select and call 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?

Schema description coverage is 100%, with issue_id and workspace_name each documented in the schema (including a workspace naming example). The description adds no format or syntax detail beyond restating the 'already have an issue ID' precondition, so the schema does the heavy lifting and baseline 3 applies.

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

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

States a specific verb and resource ('Get detailed information about a specific issue') and immediately distinguishes itself from the sibling workspace_chat by scope. An agent can tell exactly which capability this is without opening the schema.

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

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

Explicitly routes the agent: prefer workspace_chat for investigative questions (root cause, related resources, next steps) and use this tool only when an issue ID is already in hand and raw JSON is needed. Both the when and the when-not plus the named alternative are 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing beyond a safe-read implication. It says nothing about required permissions, what happens on an invalid/missing note_id, or whether access is scoped to the workspace. For a zero-annotation tool this is a notable gap.

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

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

A single front-loaded sentence with zero wasted words. It is efficient, though its brevity verges on under-specification for a tool with no annotations.

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

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

An output schema exists, so return-shape explanation is not required, and the two required parameters are fully documented in the schema. Still, with no annotations the description omits access-scoping and failure behavior that an agent would benefit from knowing.

Complex tools with many parameters or behaviors need more documentation. 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 note_id as a UUID and workspace_name as the query workspace. The description adds no format, scoping, or default information beyond that, making the baseline 3 correct.

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

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

States a specific verb ('Get') and resource ('Knowledge Base article') scoped to a lookup by ID. The 'by ID' qualifier implicitly separates it from list_knowledge_base_articles and search_workspace, 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?

The 'by ID' phrasing implies usage (call this when you already have an article UUID rather than a search query), which is adequate routing context. However, no PREREQUISITES or explicit alternatives are stated, so the agent must infer when to prefer this over list_knowledge_base_articles.

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

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

No annotations are provided, so the description carries the behavioral burden. It implies a read-only lookup and names the payload contents (configuration templates, environment variables, deployment instructions), but says nothing about permissions, auth, rate limits, or failure behavior. Adequate for a simple fetch, but thin given zero annotation coverage.

Agents need to know what a tool does to the 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; the core action is front-loaded and the follow-up sentence carries useful sequencing information rather than filler. Nothing is redundant, though it is slightly terse given no annotations.

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

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

An output schema exists, so the description need not enumerate return fields, and it still previews the kind of content returned. Combined with the search-then-get workflow guidance, an agent has enough to invoke it correctly; only permission/error behavior is unaddressed.

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

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

Schema description coverage is 100% and both required slugs are documented with concrete examples ('k8s-podresources-health', 'rw-cli-codecollection'), so the schema does the heavy lifting. The description adds no additional parameter meaning beyond what the schema already provides, which is the defined baseline.

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

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

States a specific verb and resource ('Get full details of a specific codebundle from the registry'), which is clearly distinct from the sibling search_registry and deploy_registry_codebundle. It does not name those siblings explicitly, but 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?

Explicitly positions the tool in a workflow: 'Use after search_registry to get complete information.' That tells the agent when to reach for this rather than the search tool. It stops short of stating when NOT to use it (e.g., to deploy, use deploy_registry_codebundle), so it is not 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?

With no annotations, the description carries the full burden, and it does disclose that results are 'parsed, human-readable' and enumerates the returned fields. It does not state that this is a read-only operation, note any auth/permission needs, or explain the fetch_logs download behavior, leaving meaningful behavioral gaps for an unannotated tool.

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

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

Front-loads the core purpose in the first sentence, then uses a compact bullet list for the return fields. Efficient overall, though enumerating return fields is somewhat redundant given an output schema exists.

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

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

For a simple read tool with a full output schema, the description is largely sufficient; it needn't explain return values and even does so. The main gap is the absence of guidance on how it relates to get_run_status and the run_script family.

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

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

Schema description coverage is 100%, so the schema already documents run_id, fetch_logs, and workspace_name, establishing a baseline of 3. The description adds no parameter-level detail beyond that, so it neither compensates nor detracts.

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

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

States a specific verb and resource ('Get the output artifacts from a completed script run'), which distinguishes it from nearby siblings like get_run_status and get_run_sessions. It never explicitly names or contrasts those siblings, so differentiation relies on inference from the resource noun rather than a direct comparison.

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

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

'from a completed script run' implies usage after a run finishes, giving implied context. However, it names no alternative (e.g., get_run_status vs this tool) and states no when-not condition, so the agent must infer routing. The 'completed' framing is also muddied by listing RUNNING as a possible status.

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

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

With no annotations, the description carries the full burden, and it does disclose the return shape ('structured JSON') plus the semantic scope ('recent'). It covers safety implicitly via the read-only framing and the alternative-selection rule. It does not state ordering, what window 'recent' covers, or the default limit behavior, which is what keeps it from a 5.

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

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

Front-loaded with the purpose sentence, then a compact domain gloss, then the routing note. Every block earns its place, though the parenthetical '(structured JSON)' is restated later in the NOTE, a minor redundancy.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose, domain meaning, and routing. It is nearly complete for a low-parameter read tool; only the ambiguity of 'recent' and any pagination behavior leave a small gap.

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

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

Schema description coverage is 100%, so both parameters (limit, workspace_name) are already documented in the schema, which sets the baseline at 3. The description adds no syntax, format, or ordering detail about `limit` or the workspace identifier, so it earns no credit above baseline.

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

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

States a specific verb and resource ('Get recent run sessions for a workspace') and then defines the domain object ('executions of SLX runbooks — output of health checks, troubleshooting tasks, automation runs'). It explicitly distinguishes itself from the sibling workspace_chat, so an agent can tell the two apart without opening schemas.

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

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

Gives an explicit when-not ('For investigative questions like "what ran recently for service X?" ... prefer workspace_chat') with a rationale (it can search, filter, correlate) and an explicit when-to-use ('only when you need raw JSON for programmatic processing'). This is a textbook routing instruction.

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

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

With no annotations provided, the description carries the full disclosure burden. It usefully reveals the polling pattern and the terminal status values (RUNNING, SUCCEEDED, FAILED), but omits permission requirements, error behavior for an invalid run_id, and rate limits, leaving notable 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?

Three short, front-loaded sentences with zero filler; the core purpose leads and the polling guidance and status values follow logically. 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 values need no explanation, and the description supplies the polling workflow and status vocabulary an agent needs. It is nearly complete for a simple status-check tool, with only minor gaps around error handling and auth.

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

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

Schema description coverage is 100%, so both run_id and workspace_name are already documented in the schema. The description adds no additional parameter meaning beyond what the schema provides, which is the baseline expectation when the schema already does the heavy lifting.

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

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

The description states a specific verb and resource ('Check the status of a script run'), making the tool's function immediately clear. It references the related run_script tool as a precondition but does not explicitly distinguish itself from adjacent siblings like get_run_output or run_script_and_wait, so it falls just short of a 5.

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

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

It gives clear contextual guidance: 'Poll this after run_script to check if execution has completed,' establishing when the tool fits in the workflow. However, it does not name alternatives such as run_script_and_wait (which suggests waiting outright) or state when-not to poll, so it lacks explicit exclusion guidance.

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

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

With no annotations, the description carries the burden, and it does add real value by disclosing the error path: an unknown name returns {error, available} so the agent can self-correct without a second call. However, it says nothing about permissions, side effects, or the cache/reload semantics beyond what the schema already documents.

Agents need to know what a tool does to the 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. The enumeration of return keys is somewhat redundant given an output schema exists, but the description stays short and readable.

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

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

For a simple two-parameter read tool with a full output schema, the description covers the essentials: what is returned, and what happens on failure. It is complete enough to call correctly, though a pointer to list_skills for discovery would close the remaining gap.

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

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

Schema description coverage is 100%, so both the name and reload parameters are fully documented in the schema, including the list_skills fallback and the cache/re-read behavior. 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 and resource: 'Return the full body of a skill by name.' An agent can immediately tell this is a fetch-by-identifier operation. It does not explicitly differentiate itself from the sibling list_skills or render_codecollection_skill, so it falls short of a 5.

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

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

The description gives no when-to-use guidance, no prerequisites, and no named alternative (e.g. it never says to use list_skills when the name is unknown). The only routing hint, 'Call list_skills first', lives in the parameter schema, not the description.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses return content (tasks, configuration, checks) and routes free-form questions elsewhere, but never states explicitly that this is a read-only operation, nor mentions permission requirements or rate limits. Reasonable but incomplete for a zero-annotation tool.

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

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

Front-loads the core action in the first sentence, then adds return detail and a clearly marked NOTE for routing. Three short paragraphs, each earning its place, with no redundancy.

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

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

An output schema exists, so return values need not be re-explained, and both parameters are fully covered. Usage routing is excellent; the only shortfall is behavioral disclosure (read-only nature, permissions) that no annotation supplies, but overall the definition is sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, with both required parameters (slx_name, workspace_name) documented in the schema. The description implies the SLX and workspace context but adds no syntax, format, or naming detail beyond what the schema already supplies, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get the runbook for a specific SLX') and explicitly enumerates what the runbook contains (tasks it runs, how configured, what they check). It names the sibling workspace_chat and clarifies the boundary between them, so an agent can distinguish them 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?

Gives an explicit when-to-use vs alternative: prefer workspace_chat for 'what does this SLX do?' questions, but use this tool when raw runbook YAML/JSON is needed for task authoring or programmatic inspection. This is exactly the when/when-not/alternative routing the dimension asks for.

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

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

With no annotations, the description carries the full burden and does disclose a real limitation: the response includes metadata only (id, name, scope) and not full rule/command content. That is genuinely useful negative information. It stops short of noting auth requirements, scoping behavior, or pagination, but the metadata-only disclosure is a substantive behavioral trait.

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

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

Three tight sentences, front-loaded with the core purpose, followed by scope and an important output caveat. No filler and each 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 the description need not enumerate return values, and it correctly notes the metadata-only restriction rather than repeating field details. Combined with fully covered parameters, an agent has enough to call this correctly.

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

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

Schema description coverage is 100%, so both workspace_name and persona_name are already documented, including the persona's 'persona-scoped' nature. The description mentions the optional persona but adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Get) and resource (workspace chat config) and clarifies the output is the *resolved* set of rules and commands applying to a workspace/persona. This is a meaningful distinction from siblings like list_chat_rules and list_chat_commands, though it never names those siblings to sharpen the contrast.

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

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

The description implies the use case ('the same rules and commands the workspace chat assistant sees'), which suggests when this aggregated view is preferable to fetching individual rules or commands. However, it never explicitly states when to use this versus list_chat_rules or list_chat_commands, leaving routing to inference.

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

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

With no annotations, the description carries the burden and does disclose concrete behavior: only workspace_name is accepted and other params fail with unexpected_keyword_argument. It omits auth/permission or rate-limit context, but the parameter-failure behavior is a valuable, non-obvious disclosure and the output schema covers return format.

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

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

Purpose is front-loaded, then constraints, then alternatives. Every sentence earns its place, though the SLX-routing sentence is somewhat tangential and the NOTE repeats the workspace_chat preference already implied earlier.

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

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

For a single-param tool with an output schema, the description covers purpose, accepted/rejected parameters, and sibling routing comprehensively. Nothing an agent needs to invoke it correctly is missing, and return values are documented by the output schema.

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

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

Schema coverage is 100% for the single parameter, so the baseline is 3, but the description adds meaning by enumerating the arguments that are rejected (resource_path, slx_name, filter) and the resulting error, going beyond the raw schema. This proactively prevents common misuse.

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

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

The description opens with a specific verb+resource ('Get the workspace configuration index') and clarifies the payload is structured JSON covering configured resources, SLXs, and their relationships. It clearly distinguishes itself from workspace_chat by scoping its use to programmatic processing of the raw index.

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

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

Explicitly names the preferred alternative ('prefer workspace_chat') and states the precise condition that selects this tool instead ('only when you need the raw configuration index for programmatic processing'). It also routes to commit_slx/deploy_registry_codebundle and search_workspace for adjacent needs.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the auto-discovery mechanism (walking up from cwd), the RUNWHEN_CONTEXT_FILE override, and caching behavior (reinforced by the reload param). It does not state what happens if the file is absent or what errors look like, so it falls short of exhaustive.

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

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

Front-loaded with the core action, then layered detail on the source file, discovery, override, and a bolded usage directive. Every sentence contributes, though it is slightly longer than strictly necessary for a one-parameter tool.

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

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

An output schema exists, so return values need no explanation. Given the simple input and rich output contract, the description covers purpose, mechanism, override, and invocation timing completely enough to call the tool correctly.

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

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

Schema description coverage is 100% for the single 'reload' parameter, so the schema already explains the cache-busting behavior. The description adds discovery/override context but nothing new about the parameter itself, which is the expected baseline for full schema coverage.

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

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

States a specific verb and resource ('Get domain-specific context') and immediately names the concrete source: the project's RUNWHEN.md file with infrastructure conventions, DB rules, and naming patterns. This is clearly distinguishable from the many assistant/skill/chat-rule siblings, none of which read a project context file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 closing line gives explicit, actionable timing: 'Call this BEFORE writing any task or script to understand the target environment's rules.' That removes ambiguity about when to invoke. It stops short of naming sibling alternatives or when-not-to-use, so it is not a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the output nature ('structured JSON') and the meaning of the returned data, which is useful, but says nothing about authentication, rate limits, or pagination. For a read-only get, the implicit read semantics carry most of the load, so 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 purpose is front-loaded in the first sentence, followed by a short domain definition and a clearly-marked NOTE for routing. Every sentence earns its place, though the definition sentence is a mild luxury rather than strictly necessary to invoke the tool.

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

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

With an output schema present, the description needn't explain return values, and it correctly focuses on selection guidance and the alternative. Combined with full schema coverage and no annotations, it is complete enough for correct invocation, missing only non-essential behavioral detail.

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

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

Schema description coverage is 100% and each parameter (limit, since, severity, workspace_name) is already documented in the schema with defaults and formats. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Get current issues for a workspace') and even defines what an 'issue' is in this domain, which is genuinely useful. It does not, however, distinguish itself from the sibling get_issue_details, which an agent would still need to disambiguate separately.

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

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

It gives explicit when-not guidance ('For questions like "issues related to neo4j"... prefer workspace_chat') and names the alternative along with the reason (semantic search and keyword filtering). It then states the positive selection condition ('Use this tool only when you need raw JSON for programmatic processing'), leaving nothing to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it does so well: it explains that the payload resolves the location for downstream run_*/commit_slx calls, defines 'auto_resolves' semantics, and identifies 'private' runners as preferred and 'public' as fallback. It omits auth/permission or rate-limit context, leaving a small gap for a read tool.

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

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

Front-loaded with the purpose and the key 'auto_resolves' rule, but the description then reproduces a full response-shape JSON block with inline comments. Since an output schema exists, much of that block duplicates structured data and lengthens the definition unnecessarily.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 response-shape explanation and the 'recommended'/'auto_resolves' semantics give the agent enough to call this correctly and act on the result without opening other schemas. Return values are technically covered by the output schema, but the extra semantic annotations here (preferred vs fallback, skill reference) genuinely add value.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents 'workspace_name'. The description adds only indirect meaning by tying the resolved result to the 'location' parameter of other tools. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('List runner locations') and clarifies the tool's real job — resolving which location the run_*/commit_slx tools will pick. It references the consuming siblings by name, so an agent can place it in the workflow, though it never sharply contrasts against a competing sibling for the same query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 conditional guidance: when 'auto_resolves' is True the agent should NOT pass a 'location' argument at all. That is real when-to-use guidance tied to a documented field. It stops short of naming alternative tools or exclusions, so it is clear context rather than a full routing 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?

With no annotations, the description carries the burden and does well: it discloses the critical non-obvious runtime semantics that secrets are injected as FILE PATHS, not literal values, and references the skill helper. It stops short of covering auth requirements, pagination, or side effects, but for a read-only lister this is strong context.

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

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

The purpose and critical semantics are front-loaded and the closing 'FILE PATHS, not literal values' note earns its place, but the full response-shape JSON block is largely redundant when an output schema already exists, adding length without new information.

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

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

For a single-parameter read tool that has an output schema, the description covers purpose, return semantics, and the crucial file-path caveat. Nothing essential to correct invocation is missing, though the redundant return-shape block slightly dilutes focus.

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

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

Only one parameter, workspace_name, and schema description coverage is 100%, so the schema already documents it fully. The description adds no syntax or format guidance for the parameter beyond what the schema provides, matching the baseline 3.

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

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

States a specific verb ('List') and resource ('available secret keys') plus the scope of platform grouping and mapping guidance. It is clearly distinct from all siblings, none of which expose workspace secret keys, though it does not explicitly name an alternative 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?

It implies when to use it — 'helps agents pick the right secret_vars mapping for a task' — and points to the discover-secrets skill for the read_secret pattern, but gives no explicit when-not conditions or alternative tools to compare against.

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

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

With no annotations present, the description carries the full burden and does so well: it discloses that the underlying endpoint paginates at 100, that the tool auto-paginates to completion, that 'count' is the true total and 'next' is always null, and that unsupported keywords raise unexpected_keyword_argument.

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

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

Front-loaded with the core action and the 'no filtering' constraint, then well-structured bullets for alternatives. It is somewhat verbose on pagination internals, but each block serves a distinct decision the agent must make.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, yet the description still clarifies the pagination semantics of the output. Combined with the alternative routing and parameter exclusions, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the schema already documents workspace_name and the baseline is 3. The description adds negative parameter semantics by enumerating what is NOT accepted (slx_name, filter, alias, tag), which meaningfully reduces mis-invocation risk.

Input schemas describe structure but not intent. Descriptions should explain 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 ('List ALL SLXs in a workspace'), names the return shape (structured JSON), and explicitly scopes out filtering. It also distinguishes itself from get_slx_runbook and workspace_chat, so an agent can select it without opening a sibling schema.

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

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

It gives explicit routing for three shapes of need: one SLX -> get_slx_runbook, topic search -> workspace_chat, resource search -> workspace_chat. It closes with a clear when-to-use condition ('only when you need to enumerate every SLX for programmatic processing').

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

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

No annotations are provided, so the description carries the full behavioral burden. "List" implies a read-only, non-destructive operation, and the shortName-to-persona_name explanation is useful semantic context. However, it says nothing about result volume, pagination, or ordering, which matters for a list tool with a large potential result set.

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

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

Two tight sentences, front-loaded with the core action, and every clause earns its place by defining the resource and linking the output to a downstream tool.

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

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

An output schema exists, so return values need no explanation, and the single parameter is fully documented. The description supplies the key cross-tool semantic (shortName → persona_name) and a usage trigger. Minor omission: no mention of result scale or pagination for a list operation.

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

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

Schema description coverage is 100% with a single, well-documented workspace_name parameter, so the schema already does the work. The description adds no syntax or format detail for the parameter itself; its shortName note concerns a sibling tool's input, not this one. Baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain 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 ("AI assistants (personas) configured in a workspace"), then clarifies with a definition of what an assistant is. The plural "List" clearly distinguishes it from get_assistant, create_assistant, update_assistant, and delete_assistant among the siblings.

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

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

Gives a concrete when-to-use: "Use this to discover which assistants already exist before creating a new one," routing toward create_assistant. It also cross-references workspace_chat by explaining the persona_name linkage. No explicit when-not or exclusion is stated, 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?

No annotations are provided, so the description carries the full disclosure burden. It says only 'List', revealing nothing about pagination behavior, result ordering, scope of the listing, or permissions required; the parenthetical adds minor semantic value but no behavioral context.

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

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

A single front-loaded sentence with zero filler, which is appropriately sized for a simple list tool. It is efficient but arguably too terse to be maximally useful.

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

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

An output schema exists, so return values need not be explained, and the schema fully documents parameters. However, for a tool with six parameters including several filters, the description offers no filtering context or usage framing, leaving it minimally adequate.

Complex tools with many parameters or behaviors need more documentation. 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 six parameters (page, scope_id, is_active, page_size, scope_type, workspace_name) with descriptions and defaults. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a clear verb (List) and resource (chat commands), and the parenthetical 'slash-command instructions' clarifies what a chat command is. It is distinguishable from siblings like get_chat_command, create_chat_command, and update_chat_command by its listing verb, though it doesn't explicitly name them.

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

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

There is no guidance on when to use this tool versus get_chat_command or the other chat-command siblings, nor any prerequisites or exclusions. Usage must be inferred entirely from the name.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does mention the AgentFarm internal API and possible network access, but gives no readOnly confirmation, pagination behavior, or auth/permission expectations for a 6-parameter list 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 short sentences, front-loaded with the core action and free of padding. The trailing API/network note is slightly tangential but still compact and non-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 no explanation, and parameters are fully documented in the schema. Gaps remain around usage context (filtering behavior, when to prefer this over get_chat_rule), leaving the definition minimally adequate for a filtered list tool.

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

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

Schema description coverage is 100%, so all six parameters (page, page_size, scope_id, scope_type, is_active, workspace_name) are already documented in the schema. The description adds no extra meaning beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List chat rules (workspace chat rules)'), so the operation is unambiguous. However, it offers no differentiation from the sibling listing/retrieval tools (get_chat_rule, list_chat_commands), leaving the agent to infer the boundary 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?

There is no when-to-use guidance, no exclusion criteria, and no mention of alternatives such as get_chat_rule for a single rule. The agent gets a bare listing verb with none of the routing information that the sibling set clearly needs.

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

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

With no annotations, the description carries the behavioral burden and does disclose a useful trait: all catalog data is bundled offline with no docs.runwhen.com access required, clarifying latency/permission expectations. It omits return-shape detail, but an output schema exists to cover that.

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

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

The purpose is front-loaded and the sequencing guidance is high value, but the embedded Skills list and skill URI references add length not strictly needed to call a zero-argument lister.

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

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

For a zero-param catalog lookup with an output schema and a workflow dependency on render_codecollection_skill, the description supplies exactly the sequencing and follow-up routing an agent needs; nothing material is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4; there are no parameter semantics to add beyond what the empty schema already shows.

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

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

The opening sentence gives a specific verb ('List') and resource ('supported generation-rule platforms and default render settings'), which an agent can immediately distinguish from siblings like list_indexed_resource_types or render_codecollection_skill.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explicitly when to call it ('before render_codecollection_skill when the user has not confirmed workspace-scoped vs per-resource discovery'), names the alternatives (runwhen/kubernetes/azure/aws/gcp), and points to the follow-up tool list_indexed_resource_types(search=...).

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

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

With no annotations, the description carries the full burden and does well: it discloses that the tool is 'Fully offline', reads a bundled JSON/markdown catalog from the MCP package, and needs no network access. It also adds a concrete constraint (2-char minimum search for azure/aws/gcp), though it doesn't describe output or error behavior.

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

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

Front-loads the purpose, then lists related skills, then the offline behavior and platform-specific constraints. Efficient and mostly front-loaded, though the interspersed skill list adds slight visual noise without much functional payload.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 description covers the offline execution model, the platform-scoping requirement, and search constraints. Complete enough for an agent to call correctly, with minor room on edge cases or result shape.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: the 2-character minimum on 'search' for large catalogs and the 'plural.group[/version]' syntax for unlisted Kubernetes CRD types. This is meaningful elaboration rather than repetition.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Search') and resource ('bundled indexer catalogs for valid generation-rule resourceTypes'), which is precise enough to distinguish it from generic search siblings. It does not explicitly name a competing tool, but the referenced skills ('author-generation-rules', 'commit-to-codecollection') anchor its role clearly.

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

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

Provides contextual guidance by pointing to the two skills it supports and by noting platform must match render_codecollection_skill, but gives no explicit when-to-use vs when-not or alternative-tool routing. 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?

No annotations are provided, so the description carries the full behavioral burden. It adds useful domain context about what articles feed (the Knowledge Overlay Graph) and the kinds of content they hold, but does not disclose pagination behavior, default/max limits in prose, read-only guarantees, or permission requirements. Adequate but leaves real gaps unaddressed.

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

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

Front-loaded with the core action and output format, and the NOTE is high-value routing content. The middle sentence enumerating content types (runbook context, architecture notes, troubleshooting) is somewhat expendable but does aid understanding, keeping this just below maximally efficient.

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

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

An output schema exists, so return values needn't be explained, and the description covers purpose, alternatives, and content scope. It stops short of explaining pagination or the interaction between the search and status filters, which is a minor omission rather than a blocking gap.

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

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

Schema description coverage is 100%, so the schema already documents workspace_name, limit, search, and status. The description reinforces 'filtering by status' but adds no syntax, default, or format detail beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (Knowledge Base articles / notes) scoped to a workspace, and clarifies the output format (structured JSON). The NOTE distinguishes it from the semantic-search sibling workspace_chat and from get_knowledge_base_article, so an agent can route correctly without opening a schema.

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

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

Explicit when-to-use/when-not guidance: prefer workspace_chat for semantic 'what do we know about service X?' questions, and use this tool for programmatic KB management (listing, filtering by status). Both the alternative and the selecting condition are named.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return shape, the read-then-fetch workflow, and the cross-vendor equivalence/fallback relationship with list_resources. It stops short of noting caveats such as whether the listing is complete, paginated, or scoped, but the core behavioral profile is clear.

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

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

Front-loaded with the core purpose, then the return shape, then the routing advice, so the important information comes first. The cross-vendor note is somewhat verbose but it is genuinely load-bearing because it steers clients to a different mechanism.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 already exists, so the description need not explain return values, yet it still names the fields for orientation. Combined with the explicit alternatives and fallback guidance, an agent has everything needed to call it correctly and act on the result.

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

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

The tool takes zero parameters, which establishes the baseline of 4. There is nothing for the description to add on parameter meaning, and it correctly stays silent rather than inventing inputs.

Input schemas describe structure but not intent. Descriptions should explain 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 every progressive-disclosure skill the server exposes') and immediately distinguishes itself from the sibling get_skill by noting it is the enumeration step that precedes fetching. An agent can tell what it returns and how it differs from related tools.

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

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

Explicitly says when to use it ('when you want to know what guidance is available before running a tool'), names the follow-up alternative get_skill(name), and prescribes a preference order against list_resources for MCP-resource-capable clients, naming this tool as the explicit fallback.

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

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

No annotations are supplied, so the description carries the full burden; it does disclose that results are limited to workspaces the caller can access and that no filtering is applied. It does not mention pagination, result-size expectations, ordering, or any failure/auth modes, which is a meaningful gap for a listing endpoint with no annotation coverage.

Agents need to know what a tool does to the 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 scope before the return content. The second sentence partially duplicates what the output schema already conveys, so it is efficient but not 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 zero parameters and an output schema already documenting the returned fields, the description covers what the agent needs to select and call this tool. Only minor operational details (pagination, ordering) are absent, which is acceptable given the output schema.

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

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

The tool takes no parameters (schema coverage is 100% trivially), so per the baseline there is nothing for the description to clarify. It correctly avoids inventing filter or paging arguments that the schema does not support.

Input schemas describe structure but not intent. Descriptions should explain 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 (workspaces) with an explicit scope qualifier, 'you have access to', so the agent knows the result set is permission-filtered. No sibling tool competes for this action, so the lack of explicit differentiation isn't a real gap, but there's nothing that elevates it above a clear, standard listing tool.

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

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

The intent ('get the set of workspaces available to me') is implied clearly by the name and description, and for a zero-argument listing tool that is largely sufficient. However, there is no explicit guidance on when to prefer this over e.g. get_workspace_context or search_workspace, nor any note about prerequisites such as authentication.

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

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

With no annotations, the description carries the full burden and does well: it explicitly disclaims git push and workspace mutation, discloses the side-effect of writing .runwhen files to disk, and states the environment precondition. It stops short of covering failure modes, whether rendering is idempotent, or how output_dir behaves on invalid input, so it is strong but not exhaustive.

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

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

Front-loaded with the one-line purpose, then segmented into skills, emitted layout, non-goals, platform defaults, and preconditions using bold and short paragraphs. Slightly long for a tool definition and repeats the git non-goal mildly, but every block carries distinct routing or behavioral 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 35 parameters and an existing output schema (so return values need no explanation), the description covers the pieces an agent cannot infer: the emitted file layout, the platform-dependent generation rule, required runtime environment, and the git hand-off boundary. Remaining gaps — error handling, idempotency, and any limits on repeated rendering — are minor rather than blocking.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning by grouping the discovery-related parameters — platform default 'runwhen' vs kubernetes/azure/aws/gcp per-resource discovery, and the paired resource_types/match_rules/slx_qualifiers sourced from the bundled indexer catalogs. It explains base_name (<15 chars, defaults to bundle_name) and the base64 GEN_CMD delegation, going beyond the schema text.

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

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

States a specific verb and resource ('Render a tested tool-builder task as a private Custom Discovery CodeCollection') and immediately enumerates the concrete artifacts emitted (generation rule + Jinja templates, .runwhen/SKILL_TEMPLATE.md, raw_script files). This clearly separates it from siblings like commit_slx or deploy_registry_codebundle, which the agent can rule out without opening a schema.

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

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

Names the prerequisite workflow explicitly via the runwhen-skill URIs ('build-runwhen-task (authoring + testing first)') and draws the boundary against git operations: 'does not push to git or mutate the workspace — it renders files locally ... for you to git add / commit / push.' It also routes platform selection to list_discovery_platforms/list_indexed_resource_types and states the 'Requires runwhen-local with the matching platform indexer enabled' precondition.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the async return contract (run ID + which tools consume it), the runner/location requirement, and the mandatory RunWhen script contract for four execution modes. It omits auth/permission requirements and any timeout or failure 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 purpose, then follow-up tools, then the contract block, then transport guidance — a logical order. The contract enumeration is dense but each line is load-bearing; only minor tightening is possible.

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

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

For an 11-parameter mutation-style tool with an output schema, the description covers the essentials an agent needs: execution semantics, prerequisite validation, transport encoding selection, and the required script contract. Return format details are rightly delegated to the output schema.

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

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

Schema description coverage is 100%, so baseline is 3; the description exceeds it by consolidating a mutual-exclusivity rule ('provide exactly one of script | script_base64 | script_gzip_base64 | script_path | script_base64_path') and by recommending gzip for >5KB. It adds the RunWhen contract semantics (task vs SLI, Python vs Bash) that the schema fields alone do not convey.

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

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

Specific verb+resource: 'Execute a script on a RunWhen runner for testing', with an explicit statement that it returns a run ID for polling via get_run_status/get_run_output. It distinguishes itself implicitly from the sibling run_script_and_wait by framing execution as async/monitorable, but never names that sibling to draw the line explicitly.

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

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

Gives clear context ('for testing') and an explicit prerequisite ('Use validate_script first to check compliance'). It also routes encoding choice ('use script_gzip_base64 for scripts >5KB'). It lacks explicit guidance on when to prefer this over run_script_and_wait, which is the closest alternative.

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