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

With no annotations, the description carries full burden. It discloses created files (slx.yaml + runbook.yaml or sli.yaml), output contracts for task vs SLI, and critical footguns (bash main() call, secret_vars file path injection). However, it does not explicitly state if the tool is idempotent or if it overwrites existing SLXs, nor mention permissions or rate limits. The disclosures are thorough 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?

The description is long but well-structured with tables, bullet points, and section headers. It front-loads the core purpose and usage. However, some details (e.g., footguns, output contracts) could be slightly more concise or moved to a separate section to improve scanability. Overall, every sentence serves a purpose.

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

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

Given the tool's complexity (35 parameters, 4 required, multiple script variants, task/SLI duality, and output schema), the description is remarkably complete. It covers parameter selection, usage workflows, output expectations (task returns List[Dict], SLI returns float), and caveats. The presence of an output schema reduces the need to explain return values, and the description appropriately references it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant value beyond schema per-parameter docs. It introduces a matrix explaining when to use each script variant (script, script_base64, etc.), mutual exclusivity rules, and footguns that affect parameter usage (e.g., bash main() constraint). This greatly aids parameter selection and avoids common mistakes.

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

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

The description clearly states the verb 'Commit' and the resource 'a tested script as an SLX to the workspace Git repo'. It explicitly distinguishes from sibling tools by mentioning alternative for large scripts (deploy_registry_codebundle), making the purpose specific and unambiguous.

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

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

The description provides explicit when-to-use guidance (after testing with run_script/run_script_and_wait), when-not-to-use (for very large scripts, prefer deploy_registry_codebundle), and a detailed parameter matrix for script source variants. It also explains how to combine task and SLI, covering both custom and cron-scheduler approaches.

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?

Absent annotations, the description fully discloses behavior: it's an upsert, omitted fields reset to defaults, and the short_name becomes persona_name. It also explains the broader workflow of shaping behavior with chat rules/commands.

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

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

The description is well-structured with bullet points, but slightly verbose (e.g., repeating 'assistant' multiple times). Nonetheless, it is clear and front-loaded.

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

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

With 13 parameters, no annotations, and output schema present, the description adequately covers creation behavior, upsert, and context. It doesn't detail return values (schema handles that). Missing some edge case handling notes, but sufficient.

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 3. The description adds context for short_name (mapping to persona_name) and upsert behavior, but does not significantly elaborate on other parameters beyond schema definitions.

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

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

The description clearly states the tool creates a new AI assistant persona in a workspace, distinguishes it from update_assistant and delete_assistant, and explains its relation to workspace_chat via persona_name.

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

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

It explicitly says when to use (create new assistant), when to use update_assistant (to change few fields), and mentions attaching rules/commands afterward. No ambiguity.

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 naming constraints, invocation syntax, and scheduling behavior, but omits details on permissions, idempotency, or what happens on duplicate names.

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

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

The description is very concise, with only five lines, front-loading the core purpose. Every sentence adds meaningful information without redundancy.

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

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

With 14 parameters and an output schema, the description covers essential creation and scheduling aspects. It does not explain all parameters, but the schema handles them. Additional context on skill and invocation is helpful.

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%, baseline 3. The description adds value by explaining the relationship between scheduling parameters and the skill context, going beyond the schema's individual parameter descriptions.

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

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

The description clearly states the tool creates a chat command (slash-command) and specifies naming constraints. This verb+resource combination effectively distinguishes it from sibling tools like create_assistant or create_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?

The description provides guidance on when to set scheduling parameters (cron_schedule plus sink_configs, run_as_user, assistant_name) but does not explicitly indicate when to use this tool over alternatives or when not to use it.

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

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

No annotations are provided, so the description must disclose behavioral traits. It mentions 'Uses AgentFarm internal API' but does not describe side effects, permissions, or whether the operation is idempotent. The skill reference is about wording guidance, not tool 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?

The description is only two sentences with no unnecessary words. Front-loaded with the core action. 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?

Given the existence of an output schema and full parameter descriptions, the description is mostly complete. The skill reference provides extra guidance. However, it could mention prerequisites or the effect of scope_type and scope_id interplay, but overall sufficient.

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 parameters are well-documented in the schema. The description adds a skill reference that hints at scoping and wording, but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action 'Create a chat rule' and the resource. It distinguishes from sibling tools like update or list by its verb. The skill reference adds context but is not necessary for purpose clarity.

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

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

No explicit guidance on when to use this tool versus alternatives such as update_chat_rule or when to avoid it. The skill reference hints at scoping but does not provide clear usage context or exclusions.

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

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

With no annotations, the description carries the full burden. It discloses that articles become indexed and searchable, which is a side effect, but it does not specify other behaviors like validation, failure modes, or any prerequisites. The reference to 'article scoping + lifecycle' is vague and could be expanded to explain how creation affects existing resources.

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

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

The description is two sentences plus a skill reference and content guidance—tight with no fluff. The key action is front-loaded, and the additional context (indexing, content type) is succinct. 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?

Given the availability of an output schema and a well-described input schema, the description covers the essential purpose and usage context. It could be more complete by mentioning that the workspace must exist or that content is validated, but we have the skill reference and the schema's parameter descriptions filling gaps. Overall, it is solid.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a note about content being 'informative operational knowledge,' which contextualizes the 'content' parameter, but it does not add meaningful detail beyond what the schema already provides (e.g., title max length, resource_paths examples). No additional explanation is given for parameters like abstract_entities.

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

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

The description clearly states the action ('Create a new Knowledge Base article') with a specific resource (knowledge base article) and workspace context, distinguishing it from sibling operations like update, delete, and list. It also explains the broader purpose—indexing into the Knowledge Overlay Graph for searchability—which reinforces its unique role.

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

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

The description provides context on when to use (for adding informative operational knowledge) and gives examples of suitable content, distinguishing it from other tools. However, it does not explicitly discuss when NOT to use it (e.g., for updating) or mention alternative tools, though the purpose is clear enough that exclusions are implied.

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

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

With no annotations provided, the description carries the full burden. It discloses that the deletion is soft (implied reversible) and that associated rules/commands are not automatically removed. However, it does not specify whether the operation is reversible, required permissions, or impact on existing conversations.

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 concise sentences: first defines purpose, second adds essential caveat. No redundant information. Every sentence serves a purpose.

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

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

Given the tool's simplicity and the presence of an output schema (unspecified behavior but not required per rules), the description covers the key aspects: soft-delete and side effects on rules/commands. It could mention the return value or reversibility, but overall it is adequately complete.

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

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

Schema coverage is 100% (both parameters described in input schema). The description adds no additional meaning beyond what the schema provides for assistant_name and workspace_name. Baseline 3 is appropriate.

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

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

Description clearly states the action (delete) and resource (assistant), and specifies it's a soft-delete. This distinguishes it from sibling tools like create_assistant, update_assistant, get_assistant, and list_assistants.

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

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

No explicit guidance on when to use this tool versus alternatives. Does not mention prerequisites (e.g., assistant must exist) or when not to use it. The only additional information is a cleanup note about rules/commands, which is more of a warning than usage direction.

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 must fully disclose behavior. It mentions removal from workspace and index, which is helpful, but lacks details on reversibility, required permissions, or side effects.

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

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

Two concise sentences that are front-loaded with the action and resource; no redundancy. However, the second sentence could be integrated into the first for even better conciseness.

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

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

Given the presence of an output schema and the simplicity of a delete operation, the description is largely complete. It could mention if the action is irreversible, but overall sufficient.

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 description does not add meaning beyond the parameter descriptions. Baseline 3 applies as the schema already documents the parameters adequately.

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

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

Description clearly states the action ('Delete') and the resource ('Knowledge Base article'), and specifies the scope ('removes from workspace and Knowledge Overlay Graph index'), distinguishing it from sibling tools like create or update.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., when to delete vs. archive), no prerequisites stated, and no mention of when not to use it.

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

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

Despite no annotations, the description discloses key behaviors: it uses the v4 endpoint, tombstones the SLX row, and triggers corestate reconciliation to clean up related rows. It also notes behavior matches the UI. It does not cover auth or rate limits, but the core behavior is well explained.

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

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

The description is structured into three paragraphs, each serving a purpose: core action, endpoint details, and usage clarification. It is front-loaded with the main purpose. It could be slightly more concise, but no extraneous content.

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

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

Given the input schema is fully covered, output schema exists, and the description covers behavior, usage, and parameter meaning, it is complete for an agent to select and invoke this tool correctly. It addresses potential confusion about Git-branch scoping.

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 value by providing example short names and workspace names, clarifying that parameters do not include branch/commit_message (removed from prior paths), and emphasizing the short-name format. This goes beyond the schema's simple descriptions.

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

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

The description clearly states the tool performs a 'soft-delete' of an SLX from a workspace via the v4 endpoint. It specifies the resource (SLX), action (soft-delete), and scope (workspace). It distinguishes from siblings by clarifying it is workspace-global and not Git-branch-scoped, which differentiates it from potential Git-oriented tools.

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

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

The description provides explicit guidance on when to use this tool (for workspace-scoped soft delete) and when not (avoids Git branches). It advises callers previously using a Git-oriented delete path to stop passing branch/commit_message. However, it does not explicitly mention alternative tools or when to use them, though siblings include other delete tools like delete_assistant.

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 full burden. It explains that the tool deploys a pre-built codebundle from its own repo and mentions the runbook/sli location. While it doesn't detail auth or side effects, the overall behavior is clear. A 4 is appropriate as it adds useful context beyond the basic operation.

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

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

The description is concise (5 sentences), front-loaded with the main purpose, and well-structured. It includes a sibling comparison and usage instructions with no wasted words.

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

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

Given the complexity (23 params, 7 required, output schema exists), the description provides essential context: purpose, sibling differentiation, and preparation steps. There is an output schema, so return values need not be described. A 4 reflects that it covers the key aspects without being overly detailed.

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 23 parameters. The description does not add extra meaning beyond referencing 'values from the registry'. The baseline 3 is correct since the description doesn't enhance parameter understanding.

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

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

The description clearly states the tool deploys a registry codebundle as an SLX to a workspace, with specific verb and resource. It distinguishes itself from the sibling commit_slx by contrasting the deployment of pre-built codebundles versus inline scripts.

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

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

The description provides explicit guidance on when to use this tool: after using search_registry and get_registry_codebundle to find the right codebundle. It also contrasts with commit_slx, helping the agent choose the correct tool.

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

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

No annotations are provided, so the description carries the full burden. It correctly indicates a read operation ('Get') and mentions the return includes full config. However, it does not disclose any error conditions, authentication requirements, or potential side effects. It is adequate but minimal.

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

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

The description is a single sentence, front-loaded with the verb 'Get', and contains no filler. Every word is informative.

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 getter tool with 2 parameters and an output schema (not shown but present), the description provides enough context to understand the tool's behavior. It explains what the assistant_name is and that the result is the full configuration.

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 base score is 3. The description adds the phrase 'by its short name' which is already in the schema's assistant_name description. It does not add significant meaning beyond the schema. The workspace_name parameter is straightforward.

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

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

The description clearly states the action ('Get') and the resource ('single AI assistant'), specifies it is by short name, and distinguishes from siblings like 'list_assistants' and 'create_assistant' by implying that this returns the full config of one 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?

The description implies usage when you need a specific assistant's configuration, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'list_assistants' for listing all assistants, or 'get_workspace_config_index' for overview). No when-not-to-use or prerequisites mentioned.

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

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

No annotations provided, so description bears full burden. It mentions 'full content' which hints at a richer response than list, but does not disclose any potential behavioral traits like permissions or side effects. Adequate for a read-only 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 description is a single clear sentence that efficiently captures the tool's purpose with no wasted words.

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

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

Given the presence of an output schema and the tool's simplicity, the description is adequate. It could be slightly improved by clarifying what 'full content' entails, but overall it provides sufficient context.

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

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

Schema description coverage is 100%, so the schema already documents both 'command_id' and 'workspace_name' fully. The description adds no extra semantic meaning beyond stating the resource and its retrieval method.

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

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

The description clearly states the verb 'get', the resource 'chat command', and specifies that it retrieves a single command by ID with full content. This distinguishes it from listing tools like list_chat_commands.

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

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

No explicit guidance on when to use this tool versus alternatives. Sibling list_chat_commands implies listing, but the description does not clarify when to use get vs list. Usage is implied but not explicitly 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 must disclose behavior. It states 'full content' suggesting a complete response, but does not mention permissions, rate limits, error handling, or any side effects. Adequate but lacks depth.

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

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

The description is a single sentence with no wasted words. It is front-loaded with the key action and resource. Perfectly concise for a simple retrieval 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?

Given the existence of an output schema (not shown), the description need not detail return values. It covers the basic purpose and parameters. Could mention edge cases like missing rule_id, but overall sufficient.

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% (both parameters have descriptions). The tool description adds no extra meaning beyond the schema—'by ID' simply mirrors rule_id. Baseline score is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('chat rule'), and clarifies scope ('by ID, full content'). This clearly distinguishes it from siblings like list_chat_rules (which returns multiple) and get_chat_command (different resource type).

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

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

The description implies usage when you need a single chat rule by ID, but does not explicitly state when not to use it or mention alternatives like list_chat_rules for multiple rules. No guidance on prerequisites or 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 must convey behavioral traits. It states the tool returns structured JSON, implying a read-only operation. While it lacks details on auth, rate limits, or exact output structure, it sufficiently communicates the tool's non-destructive nature.

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

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

The description is concise with two sentences and a note. It front-loads the main purpose and then provides crucial usage differentiation, making every sentence earn its place.

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

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

Given the tool has an output schema and full parameter coverage, the description is largely complete. It explains when to use the tool and what to expect. However, it could mention potential error conditions or required permissions, but overall it's 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 coverage is 100%, and the description adds no additional meaning beyond what the schema already provides for the two parameters. It merely reiterates the need for an issue ID and workspace name without extra semantic detail.

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

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

The description clearly states the tool retrieves detailed information about a specific issue in structured JSON format. It distinguishes itself from the sibling `workspace_chat` by specifying this tool is for raw JSON retrieval when you have an issue ID.

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

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

The description explicitly advises to prefer `workspace_chat` for investigative questions and to use this tool only when you already have an issue ID and need raw JSON. This provides clear usage guidance and an alternative.

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

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

No annotations are provided, so the description must cover behavioral traits. It only states the action without disclosing permissions required, whether it's read-only, expected response complexity, or error scenarios. The output schema covers return values but not 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?

The description is a single sentence with no wasted words. It is concise and front-loaded with the action.

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?

While the output schema exists to describe return values, the description lacks context about required workspace scope, potential lack of access errors, or response size. For a simple get tool, it is minimally adequate but not fully complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds no extra meaning beyond 'by ID'. Baseline 3 is appropriate as the schema already documents the parameters sufficiently.

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

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

The description clearly states the verb 'Get', the resource 'Knowledge Base article', and the method 'by ID'. It distinguishes from sibling tools like list_knowledge_base_articles which retrieve multiple articles, and create/update/delete tools which modify articles.

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

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

No guidance on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites (e.g., need to know the article ID), or any exclusion criteria. The description assumes the agent knows it's for a single article retrieval.

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

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

No annotations provided, so description carries full burden. It discloses the kind of information returned (configuration templates, environment variables, deployment instructions) but does not mention auth needs or data freshness. However, as a read operation, side effects are unlikely.

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

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

Two sentences, front-loaded with purpose, second sentence provides usage guidance. Every sentence is useful and there is no wasted 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?

Output schema exists so return values need not be described. The description covers the purpose, usage context, and the type of information retrieved. Given the tool's moderate complexity, it is sufficiently complete.

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

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

Schema coverage is 100% with both parameters having descriptions. The description adds no additional meaning beyond what the schema provides for the parameters, meeting the baseline of 3.

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

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

The description clearly states 'Get full details of a specific codebundle from the registry,' specifying verb (get), resource (full details of a codebundle), and scope (registry). It distinguishes from sibling tools like search_registry and deploy_registry_codebundle.

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 'Use after search_registry to get complete information' providing clear context on when to use this tool, and implies search_registry as the alternative for initial discovery.

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

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

No annotations provided, so description carries full burden. It discloses return content but not behavior on incomplete runs, error handling, or required permissions. The precondition 'completed script run' is implied but not enforced.

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 plus a bullet list. Front-loaded with purpose, no redundant information.

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

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

For a 'get' tool with 3 params, output schema, and no annotations, the description covers return values well. Lacks details on failure modes or preconditions, but overall 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 coverage is 100%, so parameters are well-documented in the schema. The description does not add extra meaning beyond the schema descriptions.

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

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

The description clearly states 'Get the output artifacts from a completed script run' with a specific verb and resource. It lists the returned fields (issues, stdout, stderr, status), distinguishing it from sibling tools like get_run_status or run_script.

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?

Implies usage after a script run completes ('from a completed script run'), but lacks explicit when-not-to-use or alternatives like get_run_status for status-only checks.

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

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

No annotations provided. Description mentions 'recent' but does not specify cutoff or sorting order, nor error handling (e.g., missing workspace). However, the presence of an output schema (context signal) reduces burden. Description adds some context about run sessions but lacks full behavioral disclosure.

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

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

Description is concise: one sentence for purpose, one for context, and a clear usage note. No unnecessary words, front-loaded with core action.

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

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

Given the tool's simplicity (2 params, no nested objects, output schema present), the description adequately explains purpose, usage, and output format. Minor gaps like limit behavior and sorting are omitted, but overall sufficient.

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

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

Schema coverage is 100% with parameter descriptions. Description adds general context ('workspace', 'recent') but does not provide additional semantics beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves recent run sessions for a workspace in structured JSON. It explains what run sessions are and distinguishes from sibling tool workspace_chat by specifying when to use each.

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 note advises preferring workspace_chat for investigative questions (searching, filtering, correlating) and using this tool only when raw JSON is needed for programmatic processing, providing clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries full burden. It lists possible status values (RUNNING, SUCCEEDED, FAILED) and implies it's a polling operation, which is useful behavioral context. It doesn't mention idempotency or side effects, but for a status check that's acceptable.

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

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

Three short sentences: purpose, usage hint, and status values. Front-loaded and efficient, with no superfluous content.

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

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

Given the presence of an output schema, the description adequately covers purpose, usage, and parameters. For a simple polling tool, it is complete and leaves no critical gaps.

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

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

Schema coverage is 100%, and the description adds specific usage hints (e.g., run_id from run_script, workspace example 't-oncall'), providing meaningful context beyond the schema definitions.

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

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

The description clearly states the verb 'check' and resource 'status of a script run', and it differentiates from siblings by specifying polling after run_script, making the purpose unambiguous.

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

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

The description explicitly says to poll after run_script to check completion, providing clear context for when to use. However, it doesn't mention alternatives like get_run_output for output or get_run_sessions for sessions, which would strengthen guidance.

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

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

No annotations provided, so description carries full burden. It explains both success and error return structures, including that error contains available names for self-correction. Does not explicitly declare read-only or non-destructive behavior, but the return format indicates retrieval only.

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

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

Two concise sentences front-load the main purpose and return format. No wasted words.

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

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

With no output schema provided, the description sufficiently explains the return values. For a simple retrieval tool with 2 parameters, it covers error handling and caching hint, but lacks explicit read-only declaration.

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 does not add additional parameter semantics beyond what the schema already provides for name and reload.

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

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

The description clearly states it returns the full body of a skill by name, and specifies the returned fields on success and error. This distinguishes it from sibling get_* tools, though not 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?

Provides guidance to call list_skills first if name is unknown, and mentions self-correction via error response. Does not explicitly state when not to use or provide alternatives beyond list_skills.

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 does not explicitly state that the tool is read-only, idempotent, or any behavioral traits like permissions or rate limits. However, as a get operation, the lack of transparency is not critical but still leaves room for improvement.

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

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

The description is concise and well-structured, with a clear first line stating purpose, a second paragraph detailing the return content, and a third paragraph giving usage guidance. Every sentence adds value and is front-loaded.

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

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

Given the tool has an output schema (context signals: true), the description adequately explains what the output contains: 'runbook definition including what tasks it runs, how they're configured, and what they check.' This is complete for a simple retrieval tool.

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

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

The input schema has 100% coverage with clear descriptions for both parameters: 'slx_name' (the SLX short name) and 'workspace_name' (the workspace the SLX belongs to). The description does not add any additional parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Get the runbook for a specific SLX' and specifies it returns the runbook definition including tasks, configuration, and checks. It also distinguishes itself from the sibling tool 'workspace_chat' by noting that tool provides contextual explanations.

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 usage guidance is provided: 'For questions like what does this SLX do? or what tasks does it run?, prefer workspace_chat — it provides contextual explanations. Use this tool when you need the raw runbook YAML/JSON (e.g. for task authoring or programmatic inspection).' This clearly tells when to use and when not.

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 explicitly states that 'Response includes metadata only (id, name, scope); full rule/command content is not included,' which is a key behavioral trait. It also indicates 'resolved' meaning the rules/commands are computed for the workspace. No contradictions or misleading statements.

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

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

The description is extremely concise: two short sentences and a statement about metadata. Every sentence adds value, starting with the core purpose, then the context (same as assistant sees), and a critical caveat about metadata. No wasted words.

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

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

Given the moderate complexity, the presence of an output schema, and no annotations, the description covers the essential aspects: purpose, scope, and return content limitation. It might lack details on prerequisites (e.g., workspace existence) or error conditions, but the output schema likely handles return structure. Overall sufficient for an agent.

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

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

The input schema provides 100% coverage with clear descriptions for both parameters. The tool description adds no further meaning to the parameters beyond what the schema already offers. Thus, it meets the baseline of 3, as the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: retrieving resolved chat rules and commands for a workspace. It specifies the verb 'Get' and the resource 'resolved chat rules and commands', and distinguishes from sibling tools like get_chat_command and get_chat_rule by indicating it returns a list with resolved configurations for the workspace and optional persona.

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

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

The description provides clear context: 'These are the same rules and commands the workspace chat assistant sees.' This guides when to use the tool. However, it does not explicitly state when not to use it or mention alternatives like get_chat_command for individual rules, which would improve differentiation.

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

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

With no annotations, the description discloses that the tool accepts only one parameter and returns structured JSON. It also warns about unexpected keyword arguments. Could mention authorization or performance, but overall sufficient for a simple read operation.

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

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

Three concise paragraphs: purpose, parameter constraints, and usage guidance. Every sentence adds value, and the structure front-loads key information. No superfluous content.

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

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

Given the tool's simplicity (one required parameter, read-only, output schema present), the description covers all relevant aspects: what it does, what it returns, parameter restrictions, and when to use alternatives. The presence of an output schema means return value detail is not 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% (workspace_name described). The description adds value by explicitly listing which parameters are not accepted (resource_path, slx_name, filter) and the resulting error, going beyond schema details.

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

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

The description clearly states the tool retrieves the workspace configuration index as structured JSON, providing a specific verb and resource. It distinguishes itself from siblings like workspace_chat by noting when each is appropriate.

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 advises when to use (programmatic processing) and when to prefer alternatives (workspace_chat for contextual questions). Also clarifies that only workspace_name is accepted and other parameters will fail.

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?

Although no annotations, the description covers caching behavior, auto-discovery, and env var override. Does not mention side effects or permissions, but reads are typically safe.

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 paragraphs with clear front-loading of purpose. The 'IMPORTANT' line emphasizes usage. Slightly verbose but well-structured.

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

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

Given existence of an output schema (not shown), the description adequately explains source, caching, and override without needing return value details. Complete for a read-context tool.

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

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

The sole parameter 'reload' is fully described in the schema (100% coverage), and the description adds context about caching and when to use the parameter.

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

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

The description starts with 'Get domain-specific context for building RunWhen tasks' and specifies reading a RUNWHEN.md file. This clearly distinguishes it from sibling tools like get_workspace_secrets or get_workspace_config_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 states 'Call this BEFORE writing any task or script to understand the target environment's rules and relationships.' No exclusion of alternatives, but the unique purpose makes the guideline sufficient.

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

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

The description explains that issues are 'detected problems... through automated health checks' and returns structured JSON. However, with no annotations, it omits details like read-only nature, rate limits, or pagination 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?

Concise and well-structured: first sentence states purpose, then context, then usage note. Every sentence adds value.

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

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

With full schema coverage and output schema, description provides sufficient context about purpose and alternatives. Missing minor behavioral details, but overall complete for agent understanding.

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 parameters are well-documented in schema. Description adds no additional parameter meaning beyond the schema's descriptions.

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

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

The description clearly states the tool returns 'current issues for a workspace (structured JSON)'. It differentiates from sibling workspace_chat by specifying this tool is for raw JSON programmatic processing.

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 advises when to use this tool ('only when you need raw JSON for programmatic processing') and when to prefer workspace_chat ('for questions like...'). Provides clear alternatives.

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

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

No annotations are present, so the description carries the full burden. It describes the response shape in detail, including fields like auto_resolves and recommended. It mentions backward compatibility for the locations field. It does not explicitly state if the tool is read-only, but the name and context imply it is a query without side effects.

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

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

The description is well-structured: a concise summary sentence followed by a response shape in a code block. Every sentence adds value, and the length is appropriate for the complexity of the output. No redundant or vague statements.

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

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

Given the simple input (one parameter) and the detailed response shape provided in the description, the tool is fully documented. The agent knows exactly what to expect and how to interpret the output for subsequent decisions. No additional context is 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?

The input schema covers 100% of parameters with a description for workspace_name. The tool description does not add additional parameter semantics beyond what the schema provides. The example in the schema ('t-oncall') is helpful but not extensive.

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

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

The description clearly states the tool lists runner locations with auto-resolution guidance. It provides a specific verb ('List') and resource ('runner locations'). While it doesn't explicitly differentiate from siblings, the unique response structure and guidance set it apart.

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

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

Explicit guidance is provided: when auto_resolves is True, the agent should not pass a location argument. It also explains that the recommended field tells which location sibling tools will pick when omitted. This clearly indicates when to use the tool and how to interpret its output for subsequent calls.

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 fully covers behavioral traits. It details the response shape, including platform_groups, recommended_secret_vars, runtime_semantics, and a critical note about file-path semantics. It also mentions backward compatibility.

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

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

The description is well-structured with clear sections and is reasonably concise. However, the response shape block adds length; it could be slightly shorter while maintaining clarity.

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

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

Given the tool's simplicity (one parameter) and the absence of an output schema in the input, the description provides a complete output shape and critical behavioral notes, making it fully informative.

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

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

The schema coverage is 100% for the single parameter 'workspace_name'. The description does not add extra meaning beyond what the schema already provides, so it meets the 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?

The description clearly states 'List available secret keys with platform grouping and mapping guidance', specifying a verb (list), resource (secret keys), and distinct purpose. It differentiates from sibling tools by focusing on secrets and platform grouping.

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

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

The description implies usage for retrieving secret keys and mapping guidance, but does not explicitly state when to use this tool versus alternatives or provide exclusions. No direct guidance on when not to use it.

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

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

With no annotations, the description carries the full burden and excels: it discloses the pagination behavior (auto-paginates until exhausted), the return structure (complete results, true count, next always null), the strict parameter acceptance, and the error condition (unexpected_keyword_argument). This goes beyond basic safety to explain exactly what the tool does internally.

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

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

Well-structured with clear sections: purpose, SLX definition, behavior detail, parameter constraints, and alternatives. Every sentence adds value; the use of bold and bullets improves scannability. It's appropriately sized for the 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 the tool's complexity (pagination, filtering non-support, alternatives), the description is complete: it explains the pagination effect, the exact return fields (results, count, next), the error on invalid params, and when to use it vs. alternatives. The existence of an output schema doesn't detract; the description preemptively explains the return semantics.

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

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

Schema description coverage is 100% (workspace_name already described as 'The workspace to query (e.g. 't-oncall')'), so baseline is 3. The description adds 'It accepts only workspace_name' and the prohibition on other params, which reinforces schema constraints (additionalProperties: false) but doesn't provide deeper meaning about the parameter itself.

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 'List ALL SLXs in a workspace (structured JSON)' with explicit scope ('ALL', 'no filtering'), uses a specific verb+resource structure, and immediately distinguishes itself from siblings by the emphasis on 'no filtering' and the explicit alternative for specific SLXs (get_slx_runbook) and searches (workspace_chat).

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

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

It provides explicit when-to-use guidance ('only when you need to enumerate every SLX for programmatic processing'), specifies what it does NOT accept (filtering params leading to errors), and lists clear alternatives with conditions ('One specific SLX... get_slx_runbook', 'Search/filter by topic... workspace_chat'). This fully satisfies the when/when-not/alternatives requirement.

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

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

No annotations provided, so description carries full burden. It states it lists assistants but does not disclose pagination, error behavior, or permission requirements. Minimal detail beyond the basic operation.

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

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

Three concise sentences: purpose, concept explanation with cross-reference, and usage guidance. No redundant information; perfectly front-loaded.

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

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

Given an output schema exists (not shown), description need not cover return values. The description is mostly complete for a list tool, though it could mention behavior for empty results or invalid workspace.

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, setting baseline to 3. Description does not add extra meaning beyond the schema description of workspace_name.

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

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

Clearly states the tool lists AI assistants/personas in a workspace. Distinguishes from siblings by mentioning the shortName used in workspace_chat and the use case of discovering before creation.

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 advises using the tool to discover existing assistants before creating a new one. Provides clear context but does not explicitly mention when not to use or compare with get_assistant.

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 should disclose behavioral traits. It only states it's a 'list' operation, implying read-only, but does not mention pagination (page, page_size), default values, or that workspace_name is required. No side effects or auth requirements are noted, which is a significant gap for a tool with six parameters.

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

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

The description is extremely concise (one sentence, six words) and front-loaded with the core purpose. However, it could be slightly expanded to mention the required workspace parameter without becoming verbose. Still 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?

The description is too minimal for a tool with six parameters and an output schema. It does not mention that workspace_name is required, how filters affect results, or what the output contains. While output schema exists, the description should still provide high-level context about usage scope.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning to the parameters; it does not mention any parameter names or how they affect results. Thus it provides no extra value beyond the schema.

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

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

The description 'List chat commands (slash-command instructions)' clearly identifies the verb (List) and resource (chat commands) and provides additional context that these are slash commands. This differentiates it from sibling tools like create_chat_command or get_chat_command.

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

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

No guidance on when to use this tool versus alternatives like get_chat_command (for a specific command) or create_chat_command. The description does not mention required workspace context or filtering capabilities, leaving the agent to infer usage from the schema 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 must disclose behavioral traits. It mentions 'Uses AgentFarm internal API; may require network access' but does not cover pagination, rate limits, or confirm read-only nature. The 'List' verb implies read-only but is not explicit.

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

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

The description is two sentences long with no fluff. Every sentence provides information: the action and a technical 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?

Given 6 parameters and an output schema, the description could provide more context on typical usage, such as how pagination works or the relationship between workspace_name and scope_id. It is adequate but not comprehensive.

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

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

Schema description coverage is 100%, so the schema documents all parameters. The tool description adds minimal extra meaning beyond the schema, meeting the baseline of 3.

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

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

The description clearly states 'List chat rules' with a specific resource, and adds 'workspace chat rules' to differentiate from other chat-related tools. However, it does not explicitly distinguish from sibling tools like list_chat_commands.

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

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

No guidance is provided on when to use this tool versus alternatives such as get_chat_rule or create_chat_rule. It does not mention filtering options or prerequisites.

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

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

No annotations provided, but the description discloses that all catalog data is bundled offline (no external access needed). It also mentions associated skills. Implicitly a read-only list operation, so no destructive behavior is expected.

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

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

Two paragraphs: first concise purpose, second detailed workflow. Every sentence adds value. No fluff or redundancy.

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

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

Given 0 parameters and an output schema, the description fully explains the tool's purpose, prerequisites, and post-usage steps. It covers the workflow context without gaps.

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

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

Input schema has 0 parameters (100% coverage by default). Description adds meaning by explaining the output content and how to use the results, justifying a score 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?

The description clearly states it lists supported generation-rule platforms and default render settings. It uses a specific verb ('List') and resource, and distinguishes itself from siblings by being a prerequisite to 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?

Explicitly tells when to use this tool: before render_codecollection_skill when user hasn't confirmed scope. Provides detailed next steps (ask user, then use list_indexed_resource_types). No alternatives mentioned but context is clear.

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

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

No annotations provided, but description explicitly states 'Fully offline — reads bundled catalogs' and lists skills, covering key behavioral traits.

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

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

Concise with bullet points for constraints, front-loaded purpose, no wasted words.

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

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

Given full schema coverage, output schema exists, and description covers offline, constraints, and skills, it is complete for this search 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 coverage is 100%, but description adds extra context: platform must match another tool, gives search examples, clarifies limit default.

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 'Search bundled indexer catalogs for valid generation-rule resourceTypes' with clear verb and resource, and the offline nature distinguishes it from networked 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?

Provides explicit constraints for search length and Kubernetes syntax, but does not mention when not to use it or alternative tools.

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 that the tool lists articles and returns structured JSON, and mentions the Knowledge Overlay Graph. However, it does not explicitly state read-only behavior or potential side effects, though the context implies it is a safe read operation.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. Each sentence adds value without redundancy.

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

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

Given the presence of an output schema and the comprehensive parameter documentation, the description adequately covers the tool's purpose, usage context, and differentiation from sibling tools. No additional detail is necessary.

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 parameters. The description adds value by explaining the broader context (e.g., articles feed the Knowledge Overlay Graph) and the distinction from workspace_chat, which goes beyond the schema.

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

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

The description clearly states the tool lists Knowledge Base articles in a workspace and returns structured JSON. It distinguishes from sibling tools like workspace_chat by specifying this is for programmatic KB management, not semantic search.

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

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

Explicit usage guidance: use this tool for programmatic management and filtering, and prefer workspace_chat for semantic questions. The note provides clear when-to-use and when-not-to-use instructions.

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

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

No annotations provided, so description carries full burden. It describes the return format and usage context (read-only listing), though it does not explicitly state non-destructive behavior. Still, it is transparent about being a listing operation with no side effects.

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

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

Three paragraphs, but each sentence adds value. Could be slightly shortened, but the cross-vendor note is useful. No wasted words.

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

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

For a zero-parameter listing tool with an output schema, the description is complete. It explains what it returns, when to use, and how it relates to other tools and resources.

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

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

The tool has no parameters, so schema coverage is 100%. The description does not add parameter info because there are none. Baseline 4 is appropriate as there is nothing to clarify.

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

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

The description clearly states the tool lists every progressive-disclosure skill the server exposes, with a specific verb and resource. It distinguishes from sibling list_ tools by focusing on skills, and even differentiates from 'list_resources' for the same data.

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

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

Explicitly tells when to use: before running a tool to check guidance. Provides alternatives: use get_skill or resource read. Includes cross-vendor note advising clients to prefer list_resources for MCP resource surfaces, making this the 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?

With no annotations, the description adds some value by mentioning return of 'workspace names, display names, and basic metadata.' However, it does not disclose potential side effects, authentication requirements, or pagination 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?

Two sentences, no wasted words, front-loaded with the primary purpose. Highly 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?

Given zero parameters, an output schema (not shown but exists), and minimal complexity, the description adequately covers the tool's behavior for an agent to select and use it.

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

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

No parameters exist, so baseline is 4. Description does not need to add parameter info.

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

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

Description clearly states 'List all workspaces you have access to,' which is a specific verb+resource. It distinguishes from siblings which deal with other entities like assistants, commands, or issues.

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

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

No explicit guidance on when to use this tool versus alternatives. While it's intuitive to use for listing workspaces, no exclusions or comparisons to similar tools are provided.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It details what the tool emits (standard codecollection layout, .runwhen files), explains that it renders locally or returns inline, and specifies the default generation rule and platform options. It also explicitly negates side effects (no push/mutation). However, it does not mention error behavior or performance characteristics, which slightly reduces transparency.

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

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

The description is long (multiple paragraphs) and includes many details about specific files, skills, and defaults. While every sentence adds value, the length could be overwhelming. The main purpose is front-loaded, but the density of information makes it less concise.

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

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

Given the high complexity (35 parameters, 4 required, has output schema), the description is remarkably complete. It covers output format, directory handling, platform choices, references to sibling tools like list_discovery_platforms, and the overall workflow. With an existing output schema, return values are already documented, so the description meets completeness needs.

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

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

Schema coverage is 100%, so all 35 parameters have descriptions in the schema. The tool description adds some contextual meaning (e.g., platform parameter advises calling list_discovery_platforms, script parameters explain base64 options), but overall it does not significantly deepen understanding beyond the schema defaults and descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's primary function: 'Render a tested tool-builder task as a private Custom Discovery CodeCollection.' It uses a specific verb ('render') and a specific resource ('CodeCollection'), and distinguishes itself from sibling tools by focusing on this rendering task rather than listing workspaces, chat, or other 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?

The description provides explicit guidance on when to use the tool: it renders a tested tool-builder task. It mentions related skills (commit-to-codecollection, build-runwhen-task) and clearly states what the tool does not do: 'This tool does not push to git or mutate the workspace.' It also advises calling list_discovery_platforms() before choosing a platform, giving the agent a clear workflow step.

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 that the tool returns a run ID, sends the script to a runner, and requires compliance with the RunWhen contract. It also explains encoding trade-offs and the need for a valid workspace. It does not mention potential side effects or rate limits, but for a script execution tool, the behavioral context is largely adequate.

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

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

The description is well-structured: starts with purpose, then output, then contract details, then parameter selection guidance, ending with a validation tip. It is slightly long but every sentence adds necessary information. No filler or redundancy.

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

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

Given the tool's complexity (11 parameters, 1 required, with encoding variants and script contracts) and the availability of an output schema, the description is thorough. It covers the script contract in detail, explains when to use each encoding, and suggests a prerequisite step (validate_script). No critical gaps remain.

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 adds significant value by explaining the script contract (Python vs Bash, task vs SLI), encoding recommendations (script_gzip_base64 for >5KB), and the mutual exclusivity of script_* parameters. This goes beyond the schema's field descriptions.

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

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

The description clearly states the tool executes a script for testing on a RunWhen runner, directly distinguishing it from similar tools like run_script_and_wait (which blocks) and validate_script (which only checks compliance). The verb-resource-action is specific and unambiguous.

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

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

The description provides strong usage context: it recommends using validate_script first and explains how to monitor execution with get_run_status/get_run_output. However, it does not explicitly contrast with run_script_and_wait or list conditions where one should prefer this tool over siblings, which would improve guidance.

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