Scalix Cloud

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

The description discloses key behavioral aspects beyond the annotations: it returns the model's response in the OpenAI-compatible chat-completions format and notes that tokens are billed to the project's credit pool—an important side effect not captured by the schema or annotations. It does not cover every possible behavior (e.g., error handling, timeouts), but it provides meaningful transparency for a tool with no annotation hints.

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 front-loaded with the primary action. Each sentence adds value: the first defines the action, the second explains the format and billing, and the third provides a practical pointer for model discovery. There is no redundancy or filler.

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

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

Given the tool's moderate complexity (5 parameters, no output schema, no annotation hints), the description sufficiently covers the core behavior, response format, billing implications, and how to discover model IDs. It does not fully explain every edge case, but it is complete enough for an agent to understand and invoke the tool correctly.

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

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

The input schema already provides descriptions for all five parameters (100% coverage), so the baseline is 3. The description adds context about the model family but does not introduce meaningful semantic information beyond what the schema already states. The reference to scalix_ai_models is already embedded in the schema's model parameter description, so the description does not significantly 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's function: 'Run AI inference on Scalix AI — the Scalix Lumio model family.' It specifies the primary action (sending a prompt and returning a response) and distinguishes it from the sibling tool scalix_ai_models by explicitly pointing to that tool for model ID discovery. This is a specific verb+resource pairing that removes ambiguity.

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

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

The description implies the primary use case (AI inference) and directs users to 'Discover available model IDs with scalix_ai_models,' which is a clear prerequisite guideline. It does not explicitly state when not to use the tool or name alternatives other than scalix_ai_models, but the context signals the appropriate usage scenario.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the scope of models (Lumio family and org-enabled) but does not disclose return format, pagination, or other behavioral details. No contradiction with annotations.

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

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

A single front-loaded sentence that is clear and efficient. It includes the action, scope, and purpose with no unnecessary 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 zero parameters and sufficient annotations, the description is complete enough for a listing tool. It clearly states what is listed, the scope, and that IDs are included, though it does not detail the full response structure.

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

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

The tool has 0 parameters, so the baseline is 4. The description adds value by explaining what the output includes (model IDs) and their purpose, even though parameter semantics are not applicable.

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 AI models available to the project, specifying the Scalix Lumio family and org-enabled models. It also distinguishes itself from the sibling scalix_ai_infer by noting the IDs are for use in inference.

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

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

The description implies the tool should be used to retrieve model IDs before calling scalix_ai_infer, providing clear usage context. It does not explicitly state alternatives or exclusions, but the mention of the downstream inference tool serves as strong guidance.

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

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

Annotations already indicate a destructive, non-read-only, idempotent operation. The description adds valuable context beyond annotations by disclosing the admin API key requirement and the failure mode on OAuth connections, which is significant for an agent invoking the 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 two sentences long, front-loaded with the core action, and includes the critical usage caveat. Every sentence earns its place with zero 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 moderate complexity, lack of output schema, and fully documented parameters, the description covers the necessary elements: purpose, key settings, and an important authentication constraint. It does not explicitly describe return behavior, but that is not required without an output schema.

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

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

The input schema has 100% parameter coverage, so the description need not explain parameters. The description essentially restates the three parameter purposes (MFA, email confirmation, allowed providers) without adding new semantics beyond what the schema already provides. Baseline 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's function with specific actions: configure end-user authentication, requiring MFA, email confirmation, and setting allowed providers. It uses a specific verb and resource, distinguishing it from sibling tools like database or compute 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 specifies the context (project-level authentication configuration) and provides a critical usage precondition (requires admin API key, fails on OAuth connections). It does not explicitly name alternatives, but given there is no comparable sibling tool, the guidance is 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?

Annotations already cover safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds only the action 'Create' and source, with no extra behavioral context such as whether the build is asynchronous, how long it takes, or failure modes. It does not contradict annotations.

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

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

The description is a single, direct sentence with no filler. Every word adds meaning, and it is appropriately 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 lack of an output schema, the description should explain typical return values (e.g., build ID) and next steps (e.g., use scalix_build_status to track progress). It does neither, leaving a clear gap for a create-type 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 descriptions cover all 4 parameters (100% coverage), so the baseline is 3. The description's mention of 'Git repository or Dockerfile' aligns with git_url and dockerfile parameters but does not clarify their relationship (e.g., dockerfile is a path inside the repo). It adds little 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 a specific action ('Create') on a specific resource ('container image build') with a stated source ('from a Git repository or Dockerfile'). This effectively distinguishes it from sibling tools like scalix_build_status, which is for checking build status.

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

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

The description implies when to use (when creating a build) but provides no explicit when-not-to-use or alternatives. There is no mention of the complementary scalix_build_status tool for monitoring the created build, nor any prerequisites or exclusions.

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

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

Annotations already declare the operation as read-only and idempotent. The description adds that logs are returned, which is useful, but it does not disclose any potential error behavior, rate limits, or additional side effects. It provides minimal context beyond the annotations.

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

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

The description is a single, concise sentence that is front-loaded with the key action and resource. It contains no fluff or redundant information, making it easy to scan and understand.

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

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

For a simple one-parameter read-only tool, the description is minimally viable, but it lacks contextual details such as when to call it, what the returned logs contain, or possible error cases. Since there is no output schema, the description should more fully explain the return structure.

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

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

Schema coverage is 100% because the single parameter build_id is described as 'Build ID to check'. The description does not add any further meaning or constraints to the parameter beyond what the schema already states.

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' with a clear resource 'status and logs of a build', making its function immediately obvious. It distinguishes itself from sibling tools like scalix_build_create and scalix_status by focusing on build-specific status and logs.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as first creating a build, or how this differs from scalix_status or other status-related 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?

Beyond the annotations (idempotentHint=true, readOnlyHint=false), the description adds crucial behavior: idempotent get-or-create semantics, persistence across stop/start, that parameters (vcpus, disk_gb, ssh_keys, memory_mb) are ignored if the machine already exists, and that disk_gb is fixed at creation. It also explains ssh key security implications and scope needs, giving the agent a clear safety profile.

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

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

The description is compact (three sentences) and front-loaded with the core purpose. It provides valuable distinctions (sandbox, delete) without redundancy. Every sentence earns its place: purpose, idempotency, persistence. No filler or repetition of schema details.

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 rich schema (100% coverage) and clear annotations, the description covers all critical behavioral aspects: idempotency, persistence, and parameter-ignore semantics. It does not explicitly describe return values, but with no output schema and sibling tools that operate by name, the omission is minor. Slightly more on what the function returns would make it fully complete.

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

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

Schema description coverage is 100%, and the schema already provides detailed per-parameter descriptions including constraints, defaults, and 'ignored if already exists' behavior. The tool description adds overall context (idempotency, persistence) but does not significantly enhance parameter-specific understanding beyond what the schema provides, 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 uses a specific verb+resource: 'Get or create a persistent Linux machine by name.' It clearly distinguishes from siblings by contrasting with sandbox ('Unlike a sandbox, the disk survives stop/start') and referencing scalix_computer_delete as the only erasure path, which separates it from compute lifecycle tools.

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

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

Explicitly states when to use: when a persistent machine is needed, and contrasts with sandbox. It advises that retrying is safe due to idempotency, and gives specific guidance on ssh_keys ('Only needed if a human will ssh in... exec, write_file and read_file all work without one') and scope requirements. It also points to scalix_computer_set_ssh_keys for changing keys, providing 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds meaningful context: 'AND its disk' and 'This cannot be undone' emphasize irreversibility beyond the annotation's simple flags. It does not contradict annotations.

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

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

Two sentences provide the core action, consequence, and alternative without any filler. The first sentence leads with the action and the second explains irreversibility and offers a safer alternative. Efficient and 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?

For a simple, well-annotated delete operation with one parameter and no output schema, the description fully covers the essential behavioral aspects: what is deleted, that it's permanent, and when to use a safer alternative. 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?

Schema description coverage is 100% ('id: Machine id'), so the schema already documents the only parameter. The description adds no extra parameter meaning, which is acceptable given the schema's completeness. 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 uses a specific verb ('Permanently delete') and resource ('persistent Linux machine AND its disk'), clearly stating the action and scope. It distinguishes itself from stop by emphasizing that this action is irreversible.

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 provides when to use the tool ('Permanently delete... if you may want the files back, use scalix_computer_stop'). This clearly directs the agent to an alternative for non-destructive scenarios, satisfying the 'when/when-not' 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's addition of 'persistent' and 'wait for it to finish' adds behavioral context about state persistence and synchronous execution. It also discloses the return format (exit code, stdout, stderr). While it doesn't describe permission levels or side effects beyond the command's own effects, the annotation covers destructiveness. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the main action. Every sentence provides necessary information: what the tool does, what it returns, and a crucial prerequisite. There is no redundancy or filler, making it highly concise and 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?

For a complex tool with 6 parameters and no output schema, the description covers the essential behavioral contract: execution, waiting, and return values. It omits details about the exact return structure (e.g., JSON fields) and failure modes like timeouts, but the timeout parameter is documented in the schema. It is adequate for an agent to select and invoke the tool correctly, though not exhaustive.

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

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

Schema description coverage is 100%, with each parameter (id, command, cwd, env, args, timeout_ms) having a clear description. The tool description does not add extra meaning beyond the schema, and only reinforces that the machine must be running. Given the schema already fully documents the parameters, a 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 uses a specific verb ('Run'), identifies the resource ('a persistent Linux machine'), and states the core behavior ('wait for it to finish'). It also lists the return values (exit code, stdout, stderr), which distinguishes it from sibling tools like scalix_computer_read_file or scalix_computer_write_file. The purpose is unambiguous and differentiates from machine lifecycle 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 clear context: it runs commands on a persistent Linux machine, waits for completion, and returns output. The critical prerequisite 'The machine must be running' implicitly tells the agent to check scalix_computer_list or start the machine first. However, it does not explicitly mention alternatives or when not to use it, hence not a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is well covered. The description adds value by enumerating returned fields, but it does not disclose potential nuances like pagination, filtering, or whether results include all statuses. It provides some context but is not deeply transparent.

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

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

The description is a single, well-structured sentence that immediately conveys the action, resource, and returned data. Every word contributes to understanding, with no fluff or repetition of schema details.

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

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

For a simple read-only list tool with zero parameters, good annotations, and no output schema, the description is almost complete. It tells the agent what will be listed and what fields to expect. It could be slightly more explicit about whether all machines are returned or if there are any limits, but overall it is sufficient for this tool's simplicity.

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, and schema coverage is 100% (empty schema). The baseline for zero parameters is 4, and the description adds no parameter semantics as none are needed. The description does not need to compensate for missing schema 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?

The description clearly states the action (list) and the resource (persistent Linux machines), and specifies what information is returned (status, address, resource shape). It distinguishes from likely siblings like scalix_compute_list by emphasizing 'persistent Linux machines,' 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 implies usage for listing persistent machines, but it does not explicitly contrast with related tools such as scalix_compute_list or indicate when not to use this tool. There is no alternative guidance, but the context is clear enough for basic selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the 'text file' qualifier and 'persistent machine' context, which is useful, but it does not disclose behavior for missing files, errors, or return format. Given the annotations cover the key safety traits, this is adequate but not rich.

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

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

A single, well-structured sentence conveys the essential purpose with no wasted words. It is front-loaded with the primary action and noun, making it easy to parse.

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

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

For a simple read operation with strong annotations and complete schema, the description is nearly sufficient. It states the scope (text file, persistent machine), and the lack of an output schema is acceptable since read operations conventionally return file content. A slight gap is not clarifying whether 'read out' means returning content or moving the file, but the verb 'read' implies the former.

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 provides 100% parameter coverage with descriptions for 'id' (machine id) and 'path' (absolute path). The description does not add any additional meaning to these parameters, so it meets the baseline of 3 without going 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 a specific action (read) on a specific resource (text file) from a persistent Linux machine, which distinguishes it from sibling tools like scalix_computer_write_file and scalix_computer_exec. It is concise 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?

No guidance is provided on when to use this tool versus alternatives. While the sibling tools suggest a write counterpart, the description does not mention exclusions (e.g., binary files) or recommend using this tool over exec or cat. The agent must infer usage from the tool name and 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?

Annotations mark the tool as destructive and idempotent. The description adds critical behavioral nuance beyond these hints: changes take effect immediately on running machines, sending an empty list removes all keys, and the operation is a full replacement ('Not a patch'). This fully discloses the destructive and non-incremental nature of the 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 sentences, each earning its place: first states purpose, second explains revocation and immediate effect, third clarifies full-replacement semantics and gives a caution. It is succinct, well-ordered, and free of filler.

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

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

Despite having no output schema and only two simple parameters, the description fully covers purpose, usage steps, destructive behavior, edge cases (empty list), and relationship to related tools like scalix_computer_list. An agent has all necessary context to invoke this tool safely and correctly.

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

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

Input schema already covers both parameters with 100% description coverage, including the meaning of an empty array. The description adds practical semantics by explaining the replace-not-patch behavior and advising to read current keys first before adding one, which goes beyond the schema's literal 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 opens with a specific verb and resource: 'Replace the ssh keys authorised for root on a persistent Linux machine.' This clearly distinguishes the tool from siblings by focusing on SSH key replacement, not listing, executing, or file 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 explicitly explains when and how to use the tool for revocation and removal: 'This is how you revoke... Sending an empty list removes every key.' It also warns against adding without reading current keys and points to scalix_computer_list as the source for existing keys, providing clear alternative 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 idempotentHint=true and destructiveHint=false already provided by annotations, the description adds valuable context with 'Same disk, same address', disclosing that state persists across start/stop cycles. No contradiction with annotations, and the added behavioral detail is meaningful beyond what the annotations convey.

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

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

The description is exceptionally concise—two short phrases—yet conveys the action, object, and a key behavioral promise. Every word earns its place, and the structure front-loads the action and resource.

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

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

For a simple one-parameter tool with an idempotent safety hint and no output schema, the description is complete. It states what the tool does and adds persistence context, while the sibling list and annotations provide additional context. No significant 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?

The schema already covers 100% of the single parameter 'id' with a description 'Machine id'. The tool description adds no additional parameter semantics, so it meets the baseline for high schema coverage but does not exceed it.

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

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

The description 'Start a stopped persistent Linux machine' clearly names the specific action (start) and resource (persistent Linux machine), and distinguishes it from siblings like stop, create, and delete. The phrase 'Same disk, same address' further clarifies what starting means in this context, 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 implies the tool is for stopped machines, which gives clear context for when to use it. It does not explicitly mention alternatives or exclusion scenarios (e.g., when not to use), but for a simple start operation the context is sufficient to guide selection among siblings.

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

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

The description goes beyond the annotations (idempotentHint=true, destructiveHint=false) by disclosing that the disk and network address persist, restarting returns the same files at the same address, and a stopped machine costs only its disk. This provides valuable context about state preservation and cost.

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, front-loaded with the action ('Stop a persistent Linux machine') and provides necessary context without superfluous words. 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?

This is a simple tool with one parameter and no output schema. The description covers the action, the persistence behavior, usage guidance, and cost implications, making it fully complete for an agent to select and invoke the tool.

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

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

The input schema covers 100% of the parameter (id) with a clear description ('Machine id'). The tool description adds no additional parameter semantics, so the baseline 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 stops a persistent Linux machine, with a specific verb and resource. It distinguishes itself from siblings like scalix_computer_start and scalix_computer_delete by noting that the disk and network address are kept, so this is not a deletion or a 'start' action.

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

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

The description gives explicit guidance on when to use the tool: 'Stop machines you are done with' and explains cost implications ('a stopped machine costs only its disk'). It implies that starting again will restore the machine, but does not name the alternative tool or explicitly exclude other scenarios, so it falls just short of a 5.

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

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

Annotations already declare this as destructive (destructiveHint: true) and idempotent (idempotentHint: true), so the safety profile is known. The description adds that it writes to a persistent Linux machine and only text files, but does not mention overwriting behavior or directory creation. Still, it does not contradict annotations.

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

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

The description is two sentences, front-loading the core purpose and then giving a practical usage tip. Every word is useful with no fluff.

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 write tool with comprehensive schema and safety annotations, the description is sufficiently complete. It could mention that it overwrites existing files, but the destructive hint covers that. The 'persistent' context is valuable, and the sibling tools are well differentiated.

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

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

Schema description coverage is 100%, with clear parameter descriptions for id, path, content, and mode (including decimal example). The description itself adds no extra parameter meaning, but the schema does the heavy lifting, 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 writes a text file to a persistent Linux machine, with a specific verb and resource. It distinguishes itself from sibling tools like scalix_computer_read_file and scalix_computer_exec by explicitly recommending it over shelling out with cat/echo.

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

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

The description provides clear usage context: use this to write text files without quoting issues, instead of shelling out. It names the alternative (cat/echo) but doesn't explicitly state exclusions such as binary files or when to use read_file, leaving a small gap.

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

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

With annotations providing no safety hints (all false), the description carries the burden and does well by disclosing that notes cannot be edited, that ttl_seconds controls expiry, and that pinning is for indefinite visibility. It adds meaningful behavioral context beyond the raw schema.

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

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

The description is two sentences, with the main action first. The second sentence is dense but contains essential guidance; every clause adds value. It is concise and front-loaded, though slightly complex.

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

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

For a write tool with no output schema, the description covers the essential behavioral aspects: what the board is, how to use parameters, and the no-edit rule. It is sufficiently complete for an agent to invoke the tool correctly without needing additional context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic richness by explaining the board's purpose ('news, not knowledge'), which directly informs how to use ttl_seconds, pinned, and owner_member_id. This goes beyond the schema's field descriptions and helps the agent choose appropriate values.

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

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

The description clearly states the action: 'Post a note to the crew's notice board' with a specific resource and purpose. It distinguishes from the sibling scalix_crew_board_read by emphasizing posting versus reading, and provides the board's role ('news, not knowledge').

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

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

The description gives practical usage guidance: when to set ttl_seconds for routine updates, when to pin, and when to set owner_member_id for handoff. It also explains the editing limitation ('post a correction instead'), which implies how to handle mistakes. It does not explicitly name alternative tools but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds valuable behavioral context by specifying the exact scope of data (pinned and newest unpinned) and noting the data is current as of the call, which is not implied by the annotations.

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

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

Two sentences, no wasted words. The first sentence states the function, the second gives usage guidance. It is front-loaded with the core purpose and remains highly readable.

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

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

For a simple read tool with one parameter and full annotations, the description sufficiently covers what the agent needs to know: what the board contains, when to read it, and that it is live. The lack of an output schema is mitigated by the description's clear specification of content.

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 description for crew_id is already complete ('Crew id from scalix_crew_list'), so the description adds no additional parameter semantics. With 100% schema coverage, the baseline of 3 is appropriate; the description does not need to repeat parameter 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 uses a specific verb ('Read') and resource ('crew's notice board'), clearly stating exactly what is returned: every pinned note plus the newest unpinned ones. This distinguishes it from the sibling tool scalix_crew_board_post, which handles writing to the board.

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 instructs when to use this tool ('read it before starting work so you act on the latest news') and even points to the alternative for the opposite action ('post what teammates need to know with scalix_crew_board_post'). This is clear, actionable guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds that the list returns IDs and names and explains the crew concept, but does not disclose additional behavioral traits such as whether it returns all crews or any ordering. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the primary action, and adds only relevant context about what a crew is and how to use the result. Every sentence earns its place with no redundancy.

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

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

For a no-parameter, read-only list tool, the description is complete: it states the purpose, return contents (IDs and names), and the follow-up usage with board tools. The lack of output schema is compensated by explicitly naming the return fields.

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

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

The tool has zero parameters, so there are no parameter semantics to clarify. The description correctly omits any param-related details, and the input schema is empty, providing full coverage.

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

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

The description clearly states the action 'List your crews' with the resource 'crews' and specifies the output 'ids and names'. It distinguishes this from sibling list tools by focusing on the unique crew concept and directly connecting to board 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 gives clear context that this tool is for retrieving crew IDs to use with board tools, implying when to use it. It does not explicitly mention alternatives or exclusion cases, but the connection to board tools provides a concrete usage scenario.

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

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

Annotations already indicate this is a write operation (readOnlyHint false), not idempotent, and not destructive. The description adds no additional behavioral context beyond the action of creating a schedule, such as handling duplicate names or validation of the cron expression. It does not contradict the annotations.

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

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

The description is a single, front-loaded sentence that directly communicates the tool's purpose. It is concise with no wasted words, making it easy for an agent to quickly understand the tool's role.

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

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

For a create-schedule tool with 4 parameters and no output schema, the description covers the core functionality clearly. It could elaborate on edge cases like duplicate names or response payloads, but the action is straightforward, and the schema fills in parameter details. Overall, it provides sufficient context for typical use.

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 full descriptions for all parameters, including the enum for action_type and the purpose of config. The description's mention of 'function or webhook' aligns with the schema but does not add new meaning. With 100% schema coverage, the baseline 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 uses the specific verb 'Create' and identifies the resource as a 'cron schedule', clearly stating the tool's function: running a function or webhook on a timer. This distinguishes it from sibling tools like scalix_fn_invoke or scalix_events_publish, which handle immediate execution or event publishing.

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 tool's use case is implied: it is for scheduling recurring actions. However, the description does not explicitly state when to choose this tool over alternatives, nor does it mention prerequisites or exclusions such as immediate invocation versus scheduled triggering.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this is a mutating but retry-safe operation. The description adds no extra behavioral context beyond what annotations convey, but it does not contradict them. It doesn't mention side effects, reversibility, or transaction 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, front-loaded sentence with no filler. Every word adds value: it tells what it does, on what, and how. It is appropriately concise for the tool's simplicity.

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

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

Despite having useful annotations, the description lacks any usage context, no mention of outcomes or return values, and no output schema. With no output schema to clarify behavior, the agent is left guessing what happens after applying a migration (e.g., whether it returns a status, whether it only moves forward, whether it locks the table). This is incomplete for a destructive operation.

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

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

Schema description coverage is 100%, with both parameters (version, tenant_id) having descriptions. The description only echoes the 'by version number' aspect, adding no extra meaning beyond the schema. Baseline 3 is appropriate when the schema fully documents parameters.

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

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

The description states the action clearly with a specific verb ('Apply'), a resource ('database migration'), and a method ('by version number'). It distinguishes from sibling tools like scalix_db_query or scalix_db_schema, as none mention applying migrations.

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 no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It does not mention whether it should be used after creating a branch, whether it's for a specific tenant (though tenant_id is in schema), 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?

Annotations already declare the tool read-only (readOnlyHint=true), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds value by clarifying that it returns suggestions (rather than executing or modifying) and specifying the types of suggestions (index recommendations and query rewrites). There is no contradiction with annotations.

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

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

The description is a single sentence, front-loaded with the core action, and every phrase adds value. It is concise and immediately understandable.

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

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

For a simple tool with one parameter and no output schema, the description adequately explains the purpose and the nature of the return value. The annotations cover safety characteristics. This is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema covers 100% of the parameter ('sql') with a clear description ('SQL query to analyze and optimize'). The tool description does not add additional meaning about the parameter itself; it only restates that it analyzes the query. Since schema coverage is high, the baseline 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 specifies the action ('Analyze') and the resource ('a SQL query'), and states the outcome ('return optimization suggestions including index recommendations and query rewrites'). This distinguishes it from sibling tools like scalix_db_query (which executes queries) and scalix_db_schema (which describes schema).

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

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

Usage is implied: the user has a SQL query and wants optimization suggestions. However, there is no explicit guidance on when to use this tool versus alternatives, nor any mention of scenarios where it should not be used. The description states what it does but not why to choose it over neighboring 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context such as return format, pagination, or scope details. Since annotations cover safety, a neutral score is appropriate.

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, concise sentence that directly states the tool's purpose with no fluff or redundant information. Every word earns its place.

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

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

For a zero-parameter listing tool with strong annotations, the description is sufficient, though it does not specify the output shape or the exact scope of 'all columns' (whether across all tables). The simplicity of the tool means no additional context is strictly required.

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

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

The tool has zero parameters, so the description need not clarify parameter meaning. The baseline score of 4 applies because with no parameters, the description is not expected to explain them.

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 'List' and a clear resource: 'all columns classified as containing personally identifiable information (PII)'. This clearly distinguishes it from sibling database tools like scalix_db_schema or scalix_db_search_columns.

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

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

The description states what the tool does but does not explicitly explain when to use it versus alternatives. It implies usage for retrieving PII column information but does not mention exclusions or alternative tool suggestions, leaving the context inferred.

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

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

The description discloses a critical behavioral trait: destructive statements require a two-step confirmation with CONFIRMATION_REQUIRED and a confirm_token. It also explains the return contents (columns, rows, row count, cost breakdown), going well beyond the annotations that simply mark the tool as destructive.

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 the main action stated upfront and the important confirmation mechanism explained succinctly. Every sentence adds value, with no repetition or filler.

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

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

Despite having no output schema, the description clearly states what will be returned (columns, rows, row count, cost breakdown) and covers the essential confirmation flow for destructive queries. It provides enough context for an agent to know when and how to invoke this tool correctly.

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

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

All three parameters (sql, params, confirm_token) are described in the input schema, achieving 100% coverage. The description reinforces the confirm_token usage by explaining the confirmation flow, but it does not add meaningful semantics beyond what the schema already provides.

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

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

The description begins with a clear, specific action: 'Execute a SQL query against the project database.' It also describes the return values, which distinguishes it from sibling tools like scalix_db_schema or scalix_db_migrate that serve specialized, non-query purposes.

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

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

The description clearly states the tool's purpose ('Execute a SQL query') and even shows how to handle destructive statements with confirmation. It doesn't explicitly name alternatives or when not to use it, but the context is unambiguous for a general-purpose SQL 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing this as a safe read-only operation. The description adds the key behavioral detail that it returns a relationship map based on foreign keys. It does not disclose more (e.g., output format or performance implications), but for a simple no-parameter read tool, this is sufficient given the strong annotation coverage.

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

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

The description is a single, concise sentence that directly states the purpose without any unnecessary words or repetition. It is front-loaded and efficient, earning a perfect score for conciseness and structure.

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

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

For a tool with no parameters, no output schema, and strong read-only annotations, the description completely covers what the tool does: it retrieves the foreign-key relationship map. It is not overly complex, and no additional context is needed to understand its basic function. The sibling tool list suggests other db tools, but the description stands alone adequately.

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

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

The tool has zero parameters, so there is no schema to elaborate on. The baseline of 4 applies because with no parameters, the description has no additional burden. It appropriately focuses solely on the tool's action and result.

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

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

The description clearly states the tool's function: 'Get the relationship map showing how tables are connected via foreign keys.' It uses a specific verb ('Get') and resource ('relationship map'), and the foreign key detail distinguishes it from sibling tools like scalix_db_schema or scalix_db_table. The purpose is unambiguous and immediately understandable.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. While the name implies relationships, it does not explicitly contrast with related tools such as scalix_db_schema or scalix_db_table, nor does it describe prerequisites or typical use cases. Users must infer usage from the purpose alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds scope ('all tables, columns, types, and relationships') but does not mention potential performance costs, output size, or whether the response is paginated. It is adequate but not enhanced beyond the annotations.

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

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

The description is a single, concise sentence that is front-loaded with the action and resource. Every word contributes meaning, with no fluff or repetition.

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

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

For a tool with no parameters and no output schema, the description provides a clear list of what will be returned (tables, columns, types, relationships). It is complete enough for an agent to understand the tool's purpose and output, though it does not describe the exact response format or any edge cases like permissions or size limits.

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

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

The tool has zero parameters, so the baseline per the rubric is 4. The description does not need to explain parameters, and the empty schema already covers all parameter semantics. No additional meaning is required.

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

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

Description clearly states the verb 'Get' and the resource 'full database schema' with explicit scope: tables, columns, types, and relationships. This distinguishes it from sibling tools like scalix_db_table (specific table) and scalix_db_relationships (relationships only).

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

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

The description implies the tool is for retrieving the entire schema, but it does not explicitly mention when to use it over alternatives such as scalix_db_table or scalix_db_search_columns. No exclusions or alternative scenarios are stated, so guidance is only implied.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is known. The description adds the cross-table scope but does not disclose additional behavioral details like output format, pagination, or limits, which is acceptable given the annotations.

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

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

The description is a single, front-loaded sentence that immediately conveys the tool's purpose. Every word is informative with no redundancy or filler.

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

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

For a simple search tool with one parameter, no output schema, and strong annotations, the description is adequate. It clearly conveys what the search does, though it could specify what fields are returned (e.g., table name, column type) to be 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% and the parameter description in the schema ('Search term to match column names or types') directly mirrors the tool's description. The tool description adds no extra semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific action ('Search'), a specific resource ('columns'), and a clear scope ('across all tables'). It is distinct from sibling tools like scalix_db_schema or scalix_db_table, which presumably target specific tables or schema-level details.

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

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

The phrase 'across all tables' clearly signals when to use this tool (when you need to find columns globally by name or type) and implicitly differentiates from table-specific or schema-level tools. However, no explicit alternatives or exclusions are mentioned, keeping it slightly below a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds the content of the return (columns, indexes, foreign keys) but does not disclose behavioral aspects like permissions, rate limits, or error behavior beyond what annotations provide.

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

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

The description is a single, front-loaded sentence with no filler. Every word adds value, clearly stating the action and the included details.

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

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

Given the tool's simplicity (one parameter, no output schema), the description suffices. It mentions the key output components (columns, indexes, foreign keys) and does not leave major gaps. It could note potential missing details like table statistics, but for this complexity level, it is fairly complete.

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

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

The input schema covers the only parameter 'table' with a clear description ('Table name to inspect'), so schema coverage is 100%. The tool description does not add extra meaning beyond what the schema already states, so a 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's purpose: obtaining detailed information about a specific database table. It names the resource type ('database table') and the kind of detail ('columns, indexes, and foreign keys'), which differentiates it from sibling tools like scalix_db_schema or scalix_db_relationships.

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

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

The description implies when to use the tool (when you need details about a table) but does not explicitly compare to sibling tools such as scalix_db_schema for whole-schema information or scalix_db_query for data retrieval. No exclusions or alternative conditions 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?

The description goes beyond the annotations by explaining that it is pattern-matching (no AI model), returns SQL without executing, supplies a confidence score, and that low confidence means the table was guessed. It also mentions 'tables_used' in the output, giving the agent a clear picture of the tool's behavior and output beyond the safe read-only, idempotent, non-destructive traits already annotated.

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 three sentences, each serving a purpose: the first states the core function and scope, the second explains the output and confidence, and the third gives usage guidance and alternatives. It is front-loaded with the main action and contains zero redundant text.

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

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

For a single-parameter tool with no output schema, the description is remarkably complete. It covers purpose, limitations, return format (SQL, confidence score, tables_used), execution next steps, and when to use a different approach. There is no need for additional 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?

With 100% schema description coverage, the baseline is 3, but the description adds meaningful constraints on the 'question' parameter by limiting it to simple questions (counts, averages, filtered selects on a named table). This helps the agent decide whether to invoke this tool or use an alternative, going beyond the schema's generic example.

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 translates a plain-language question into a candidate SQL query using pattern-matching against the live schema, with a specific verb and resource (text-to-SQL). It distinguishes itself from siblings by noting it does not execute the query and is for simple questions only, such as counts, averages, and filtered selects on a named table.

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 defines when to use this tool (simple questions like counts, averages, filtered selects) and when not to (complex questions), directing users to read scalix_db_schema and write SQL directly for complex cases. It also tells the agent to run the resulting SQL with scalix_db_query, providing clear alternatives and follow-up actions.

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

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

The description adds that it 'Returns DNS records to configure,' which is useful behavioral context beyond annotations (which are all false). However, it does not disclose idempotency, handling of duplicate domains, or any prerequisites like domain ownership verification. Annotations provide no safety profile, so the description carries a moderate burden but is not fully transparent.

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

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

The description is two concise sentences, front-loaded with the primary action and followed by a key return detail. Every word earns its place, with no redundancy.

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

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

For a simple one-parameter tool with no output schema, the description is adequately complete: it tells what the tool does and what it returns. It does not detail the exact structure of the DNS records, but that is not critical for invoking the tool correctly. The presence of sibling tools (list, verify) completes the domain workflow 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?

The input schema already fully describes the 'domain' parameter with an example (100% coverage). The description mentions 'custom domain' but does not add new meaning to the parameter beyond what the schema provides. Baseline 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 'Add a custom domain to the project' with a specific verb and resource. It distinguishes itself from sibling tools like scalix_domain_list and scalix_domain_verify by indicating the action is to add, not list or verify.

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 context for use is clear: this tool is for adding a custom domain. It does not explicitly mention alternatives or exclusions, but the sibling tools (list, verify) imply different use cases. This is a clear enough context without needing explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the detail about SSL/verification status, but does not disclose any additional behavioral aspects such as pagination, response format, or whether it returns system domains. This adds some value but is not rich.

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

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

The description is one clear, front-loaded sentence that immediately conveys the primary action and scope. It contains no filler or redundancy, making it highly concise.

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

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

For a read-only list tool with no parameters and strong annotations, the description is largely complete. It specifies the resource (custom domains) and the included status fields. However, it does not describe the exact return shape or any pagination behavior, which would be helpful given no output schema is provided.

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

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

The input schema has zero parameters, so schema description coverage is effectively 100%. Per the rubric, a baseline of 4 is appropriate for a tool with no parameters, and the description does not need to compensate for missing parameter information.

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

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

The description clearly states the tool lists all custom domains and includes their SSL/verification status. It uses the specific verb 'List' and identifies the resource ('custom domains'), which distinguishes it from sibling tools like scalix_domain_add and scalix_domain_verify that perform different 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 implies usage for listing domains but provides no explicit guidance on when to use it versus alternatives. It does not mention that scalix_domain_add is for adding domains or scalix_domain_verify for verification, so the context is inferred from the tool name and sibling list rather than stated.

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

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

While annotations already signal non-read-only, idempotent, and open-world behavior, the description adds concrete actions—DNS verification and SSL provisioning—that are not inferable from annotations alone. It doesn't go into caveats like duration or failure modes, but it does disclose the core 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 a single, compact sentence that front-loads the core action and the secondary action. It contains no superfluous words and is appropriately concise for the tool's simplicity.

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 there is no output schema, the description could be expected to explain return values or expected effects, but it only states the actions. The tool's prerequisites (e.g., domain already added) are not mentioned, making it slightly incomplete, though the one-parameter scope keeps it 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?

The single parameter 'domain' is fully described in the schema with a clear description, achieving 100% coverage. The tool description adds no extra parameter-level detail beyond what the schema provides, so it meets the baseline for complete schema coverage.

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

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

The description clearly states the tool's function with a specific verb ('Verify') and concrete resources (DNS configuration, custom domain, SSL certificate). It distinguishes from sibling tools like scalix_domain_add and scalix_domain_list by focusing on verification and provisioning rather than creation or listing.

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 no explicit guidance on when to use this tool versus alternatives, nor does it reference the domain lifecycle (e.g., after adding a domain). It implies usage but doesn't state prerequisites or conditions, leaving the agent to infer appropriate timing.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the description does not need to restate that this is a mutating but non-destructive operation. However, the description adds little beyond the schema: it gives an example event_type format ('user.created'), but does not describe potential side effects, error conditions, or delivery semantics. It meets the baseline but does not enrich behavioral understanding significantly.

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 and directly states the purpose and provides a relevant example. Every word earns its place; there is no fluff or unnecessary repetition.

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

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

For a simple publish tool with three fully described parameters and no output schema, the description plus schema covers the necessary input context. It could mention whether a confirmation or response is returned, but that is not required given the absence of an output schema. The description is sufficient for an agent to invoke the tool correctly in most scenarios.

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 each parameter already has a description (e.g., 'Topic ID to publish to', 'Event type/name, e.g. user.created'). The description reiterates the event_type example but adds no new semantic meaning beyond the schema. Therefore, a baseline 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's action: 'Publish an event to a topic.' This uses a specific verb and resource, and is distinguishable from sibling tools like scalix_events_topics (which likely lists topics) by its focus on publishing. It also specifies the required inputs (event_type and data payload).

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

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

The description explains what the tool does but provides no explicit guidance on when to use it vs. alternatives, nor any exclusions or prerequisites. The usage context is implied by the tool's nature (publishing events) but not spelled out. Sibling tools like scalix_events_topics suggest related functionality, but no comparison is made.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds behavioral context about publishing failures for non-existent topics, which helps the agent understand the operational significance of the tool beyond the annotations.

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

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

Two sentences, with the first stating the core action and output, and the second providing usage context. No wasted words, front-loaded and clearly 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?

For a simple list tool with no parameters and no output schema, the description covers the essential information: what is listed, what fields are returned, and why/when to use it. It is complete for its complexity level.

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

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

The tool has zero parameters, so the description cannot add parameter semantics. Baseline for 0 params is 4. The description does mention the return fields (ID and name), which is useful for the agent.

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

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

The description clearly states the tool lists event-bus topics with ID and name, using a specific verb and resource. It distinguishes from siblings by explicitly linking to scalix_events_publish for topic verification.

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 states when to use this tool: 'Use this to find or verify a topic_id before publishing with scalix_events_publish' and explains the consequence of not doing so. This provides clear context and a specific workflow.

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

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

Adds valuable context beyond annotations: billing model, isolation, and the deploy-then-invoke relationship. Annotations already indicate a mutate operation (readOnlyHint=false), and description aligns with that without contradiction.

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

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

Two sentences with the main action front-loaded, followed by a relevant next-step pointer. No redundant words or filler.

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

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

Covers the core purpose, deployment source, and next step (invoke). Though there is no output schema or return value information, the description is adequate for a deployment tool given the sibling 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?

The input schema provides 100% description coverage for all three parameters (name, image, runtime). The description adds no parameter-specific details, so the baseline score of 3 applies.

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

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

Clearly states 'Deploy a Scalix Function' with specific execution attributes (serverless, per-request billed, isolated microVMs) and explicitly ties to the sibling scalix_fn_invoke for the next step, differentiating it from other 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 clear context for when to use (deploying a function from a container image) and implies the follow-up action (invoke), but does not explicitly mention when not to use or name alternative tools. No exclusions, but context is 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds no additional behavioral context such as side effects, sync/async behavior, error handling, or auth requirements. It simply restates the action without informing the agent of consequences beyond what annotations provide.

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

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

Single sentence, front-loaded with verb, no filler. Perfectly concise for a simple tool.

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

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

For a function invocation tool with no output schema and no mention of return behavior, the description leaves the agent without expectations about results, errors, or whether invocation is synchronous. Sibling tools suggest more complex workflows that this tool doesn't clarify, making the description incomplete.

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

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

Schema description coverage is 100% (both function_id and data have descriptions), so the baseline is 3. The description's phrase 'with a JSON payload' adds no new meaning beyond the existing schema field 'data'.

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

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

The description uses a specific verb ('invoke') and identifies the resource ('deployed function'), making the tool's purpose clear and distinguishing it from deployment and listing tools. It also specifies the input type ('JSON payload').

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 like scalix_sandbox_run or scalix_ai_infer. The description does not mention usage scenarios, prerequisites, or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not reiterate these. It adds minimal context beyond the annotations, only specifying that the function lists 'deployed' functions. For a simple read-only list operation, this is acceptable, but no additional behavior (e.g., pagination, result format) is disclosed.

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

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

The description is a single, straightforward sentence: 'List all deployed serverless functions.' It is front-loaded with the action verb and clearly states the object. No unnecessary words or redundancy are present, making it highly concise.

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

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

For a simple no-parameter list tool, the description is sufficient to understand its core purpose. However, it does not mention the return format or any filtering capabilities (which are none). Given the absence of an output schema, a brief note on what the list returns might be expected, but the tool's simplicity makes the description reasonably complete.

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

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

The tool has zero parameters, and the input schema is empty, so there is no parameter information for the description to enhance. The baseline for zero-parameter tools is 4, and the description adequately represents the operation without needing to discuss parameters.

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

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

The description uses a specific verb 'List' with a precise resource 'deployed serverless functions', making it clear what the tool does. This distinguishes it from sibling list tools like scalix_compute_list and scalix_run_list by naming 'serverless functions' specifically. The scope 'all' is also explicit, leaving no ambiguity about its target.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. Given the presence of several list-style siblings (e.g., scalix_compute_list, scalix_run_list, scalix_project_list), an agent may not know which list tool to choose without further context. The context is implied by the name, but there is no explicit comparison or exclusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond annotations by detailing the not-found error behavior for missing keys or expired TTLs, adding valuable runtime context that the annotations do not provide.

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

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

Three concise sentences accomplish everything: state the purpose, describe the return/error behavior, and provide usage guidance. There is no redundancy or filler, and the content is front-loaded with the 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?

For a simple tool with one parameter and no output schema, the description is complete: it covers what the tool does, what it returns, what happens on failure, and how to discover keys when needed. Nothing essential is missing.

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

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

The input schema provides 100% coverage for the single 'key' parameter with a clear description ('Exact key to look up (case-sensitive)'). The description's mention of 'by exact key' and case-sensitivity adds minimal value beyond what the schema already states. Baseline 3 is appropriate because the schema fully documents 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 a specific verb ('Read') and resource ('project's key-value store') with a clear scope ('by exact key'). It distinguishes itself from siblings like scalix_kv_list (key discovery) and scalix_kv_set (write) by explicitly focusing on single-key reads.

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 names scalix_kv_list as the alternative for discovering keys by prefix, giving clear guidance on when to use this tool instead. It also conveys the expected behavior for missing/expired keys, further contextualizing appropriate use.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, covering safety and side-effect expectations. The description adds no behavioral context beyond what the schema already states—no mention of return format, ordering, pagination, or key limits. It does not contradict annotations but adds zero transparency value.

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

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

A single compact sentence that front-loads the verb and resource, with no filler or repetition. Every word earns its place, making it 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?

For a simple one-parameter tool with full schema coverage and strong annotations, the description is sufficient for an agent to understand what the tool does. It does not describe the output format, but listing keys generally implies an array of key names, so this is largely inferable. A brief example of the return structure would push it to a 5.

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

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

Schema coverage is 100%: the prefix parameter is described as 'Filter keys by prefix'. The description echoes this and clarifies that filtering is optional, but it does not add additional meaning beyond the schema. Baseline 3 is appropriate here since the schema handles parameter documentation fully.

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

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

Clearly states the verb 'List', the resource 'keys in the key-value store', and the optional prefix filter. This distinguishes it from siblings like scalix_kv_get (retrieve a single key) and scalix_kv_set (write a key) by focusing on enumeration.

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

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

The description gives clear context: use this tool to enumerate keys, optionally scoped by a prefix. It does not explicitly mention alternatives or when not to use it, but the purpose is unambiguous enough for a list operation. A pointer to kv_get for specific lookups would make it a 5.

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

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

The description adds the TTL aspect, which is beyond the annotations. Annotations already declare destructive and idempotent hints, so the baseline is met. But it does not elaborate on overwrite behavior or error semantics, so it remains average.

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?

One short sentence, front-loaded with the action and object, 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 simple write operation with fully documented schema and annotations, the description is sufficient. It lacks only discussion of edge cases like overwrites, but given the simplicity and sibling context, it is largely complete.

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

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

The schema covers all parameters with descriptions, and the tool description just restates key-value pair and TTL without additional parameter semantics. Baseline 3 is appropriate due to high schema coverage.

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

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

The description uses the specific verb 'Set' with resource 'key-value pair', clearly distinguishing from siblings kv_get and kv_list which are read operations. The optional TTL is mentioned, aligning with the schema.

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

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

The description clearly indicates the tool is for setting key-value pairs, which is distinct from the read-only siblings kv_get/kv_list. However, it does not explicitly state when not to use it or name alternatives, so not a full 5.

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

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

Adds valuable behavioral detail beyond the annotations: returns project ID/name/slug, requires admin API key, and fails on OAuth connections. No contradiction with the annotations.

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

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

Three concise sentences, front-loaded with the core action and return data. Every sentence adds essential information without filler.

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

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

For a simple create operation with no output schema, the description fully covers return values, authentication requirements, failure mode, and the next step. No important 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?

The input schema already documents all three parameters with 100% coverage, so the description does not need to repeat parameter semantics. It adds no per-parameter detail, matching 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?

Clearly states it creates a project within an organization, using a specific verb and resource. This distinguishes it from sibling tools like scalix_project_list by the action, and it names the return values.

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

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

Provides explicit usage context: requires an admin API key, will fail on OAuth connections, and includes a follow-up action to issue an API key separately. This gives 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?

The description adds valuable behavioral context beyond the annotations: the authentication requirement and failure mode on OAuth connections. It also clarifies the scope ('every project' in an organization). The readOnlyHint and idempotentHint are consistent with the 'List' operation, so no contradiction.

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 cover the function, output, usage, and a critical caveat. Every sentence earns its place with no waste 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?

The tool is simple (one parameter, no output schema) and the description covers the operation, return fields, usage context, and authentication caveat. This is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the description includes the org_id parameter in context ('in an organization'). The description does not add deeper semantic details beyond what the schema already provides, so a baseline 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 lists every project in an organization and specifies the returned fields (ID, name, slug). It distinguishes itself from sibling tools by being specifically for projects and by noting its role in resolving project IDs for project-scoped tools.

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

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

Explicitly instructs when to use the tool ('before calling project-scoped tools') and provides a critical caveat about authentication requirements (admin API key required, fails on OAuth). This gives clear usage direction and boundaries.

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 annotations already mark destructiveHint: true, the description adds crucial behavioral details: stops running instances, releases public HTTPS URL, erases volumes, discards revisions, and confirms irreversibility. This goes far beyond the annotation's binary signal.

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: first states the action and immediate irreversibility, second lists all consequences and offers a safer alternative. Every word earns its place; no redundancy or fluff.

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

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

For a destructive tool with one parameter and no output schema, the description fully covers what happens, why it matters, and how to avoid unwanted deletion. No gaps remain for the agent to infer.

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 already describes the only parameter 'id' as 'Service ID (from scalix_run_list)' with 100% coverage. The description adds no new param-specific semantics, but none are needed given the simple, well-documented 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 opens with 'Permanently delete a Scalix Run service', using a specific verb and resource. It explicitly distinguishes itself from siblings by stating that scalix_run_rollback cannot undo it and scalix_run_scale is the alternative for pausing.

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

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

It provides clear when-to-use guidance (permanent deletion) and an explicit alternative for a common use case: 'To stop paying for an idle service without losing it, set min_instances to 0 with scalix_run_scale instead.' This is exemplary 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 annotations providing only mutability flags (readOnlyHint=false, etc.), the description carries the burden of behavioral disclosure. It adds critical context: creates or updates a service, includes health checks and public HTTPS URL, autoscales between min and max instances, scale-to-zero when min=0, and per-vCPU-hour billing. No contradiction with annotations; openWorldHint is consistent with creating external 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 four sentences, each earning its place: the first defines the operation, the second details feature set and revision behavior, the third covers pricing, and the fourth points to rollback. No fluff, no redundancy, and the most important action is front-loaded.

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

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

For a complex deployment tool with 6 parameters and no output schema, the description covers the core behavior (create/update), key features (health checks, public URL, autoscaling), cost implications, and a rollback safety net. It does not explain return values, but with no output schema that is not required. The only minor gap is not mentioning the build prerequisite, but that is covered in the image parameter's schema description.

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. The description adds value by clarifying the relationship between min_instances and max_instances ('autoscaling between...') and the billing implication ('Billed per vCPU-hour while instances run'), which gives cost context to instance counts. The image parameter's external-registry restriction is already in the schema, so the description does not need to repeat it.

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

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

The description opens with a specific verb+resource pairing: 'Deploy a long-running container service on Scalix Run from a container image.' It clearly distinguishes this tool from serverless function deployment (scalix_fn_deploy) by emphasizing long-running containers, and from rollback by naming scalix_run_rollback. The behavior of creating a new service or a new revision is explicit.

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

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

The description states the primary use case ('deploy a long-running container service') and explicitly points to scalix_run_rollback for undoing a bad revision. It does not explicitly contrast with scalix_run_scale or scalix_build_create, though the schema hints at the build prerequisite. Clear context but lacks explicit when-not-to-use alternatives.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds scoping ('in the project') and the 'all' qualifier, but does not disclose return format, pagination, or filtering behavior. This is adequate given the strong annotation coverage.

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

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

A single succinct sentence that front-loads the verb and clearly identifies the target resource. No wasted words 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?

This is a simple list operation with no parameters, strong annotations, and a self-explanatory output (a list of deployed container services). The description fully covers what an agent needs to know for selection and invocation.

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

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

The tool has zero parameters and an empty schema, which fully documents that. With 0 parameters, the baseline is 4; the description correctly focuses on the operation itself without needing parameter explanations.

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 (List), the resource type (deployed container services), and the scope (in the project). This distinguishes it from sibling list tools like scalix_compute_list or scalix_fn_list, 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 implies the tool is used for listing deployed container services, but it does not explicitly state when to prefer it over other list tools or mention exclusions. The context is clear enough for basic selection, but no alternative guidance is provided.

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

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

The description discloses meaningful side effects beyond annotations: 'Traffic switches to the target revision; the replaced revision is kept and can be redeployed later.' This explains non-destructive behavior and state changes, complementing the destructiveHint=false annotation without contradiction.

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

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

Three dense sentences, no repetition, and front-loaded with the core action. Every sentence contributes information about usage, behavior, or prerequisites.

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 only two parameters and no output schema, the description covers the inputs, the resulting behavior, and the pre-requisite for obtaining the ID. It is complete for an agent to invoke the tool correctly without further clarification.

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 the description adds semantics: 'omit revision to return to immediately previous one' clarifies the default behavior, and 'Service ID (from scalix_run_list)' ties the id parameter to a reliable source. This goes beyond the schema's basic types.

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

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

The description uses a specific verb ('Roll back') and resource ('Scalix Run service'), clearly distinguishing it from sibling tools like scalix_run_deploy or scalix_run_scale. It also clarifies optional behavior for the 'revision' parameter, adding precision.

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

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

The description gives explicit context: 'Use scalix_run_list to see services and their current revisions' provides a prerequisite and a sibling alternative. It does not explicitly contrast with deploy/scale, but the rollback purpose is clear enough for basic guidance.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, so the agent knows this is a safe mutation. The description adds valuable context: 'Takes effect immediately' and behavioral consequences of min_instances (warm instances, higher cost, scale-to-zero). No contradiction with annotations.

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

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

The description is four short sentences, each earning its place: purpose, behavioral trade-offs, immediate effect, and ID lookup. It is front-loaded with the core action and avoids 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 no output schema, the description adequately covers what the tool does, immediate effect, cost/performance implications, and how to obtain the required id. It could mention that omitting both bounds may be a no-op, but with annotations and 100% schema coverage, this is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with all three parameters clearly described. The description adds only minor nuance about raising min_instances (no cold starts, higher cost), but this is largely redundant with the schema's note about 0 = scale-to-zero. Baseline 3 applies because the schema already carries the parameter meaning.

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

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

The description clearly states the tool changes autoscaling bounds of an existing Scalix Run service without redeploying, using a specific verb and resource. It distinguishes from sibling tools like scalix_run_deploy and scalix_run_rollback by focusing on scaling bounds and immediate effect. References to scalix_run_list further anchor its purpose.

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

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

The description implies when to use this tool: to adjust autoscaling without redeploying, and tells the agent to find service IDs with scalix_run_list. It explains trade-offs (warm instances vs scale-to-zero) but does not explicitly name alternatives or state when not to use it. The 'without redeploying it' phrase hints at the 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?

Annotations already provide safety profile (readOnly=false, openWorld=true). The description adds the 'isolated' context and return of stdout/stderr, which is useful, but it doesn't disclose potential side effects or network access nuances. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the primary action, and contains no fluff. Every word 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 a rich schema covering all parameters and no output schema, the description provides return behavior (stdout/stderr) and execution context. It doesn't explain files or packages relationships, but schema handles those details, making it sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100%, so all parameters are already documented. The description adds no extra meaning beyond what the schema provides, aligning with 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 the tool executes code in an isolated sandbox, with a specific verb and resource. It lists supported languages and differentiates from siblings like scalix_computer_exec or scalix_fn_invoke by emphasizing isolation and language support.

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 context of an isolated sandbox implies safe, throwaway code execution, but no explicit when-to-use alternatives or exclusions are given. It doesn't mention when to prefer this over scalix_computer_exec or scalix_fn_invoke, so usage is only implied.

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

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

The description adds valuable behavioral context beyond the annotations: it discloses the deduplication behavior ('syndicated copies collapsed to the source that published first') and the provenance fields returned. This goes beyond the read-only and idempotent hints by explaining exactly what happens during a search, which is useful for setting expectations.

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, front-loaded with the action and resource, then elaborates on the behavior and output. Every sentence adds meaningful information without redundancy, making it both concise and 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?

The description is quite complete for a search tool. It explains the scope, default behavior, and what fields are returned (source, date, region, canonical flag), which covers the absence of an output schema. It lacks details on pagination or error cases, but these are not critical for a straightforward search tool, and the annotations already cover safety and side effects.

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 some context about the overall nature of the index and the original_only default, but it does not add per-parameter details beyond what the schema already provides, such as the meaning of region codes or the q parameter. It doesn't compensate for any gaps because there are none.

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 a specific verb and resource: 'Search the Scalix original-source index'. It distinguishes the tool from open web search and siblings by describing the curated set of original publishers (newsrooms, wires, regulators), which is unique among the listed sibling 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 clear context of when to use: searching original sources, not the open web. It explains the default behavior of returning originals only and collapsing syndicated copies, giving users a strong sense of intended use. However, it does not explicitly name alternatives or state when not to use it beyond the 'not the open web' comment.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only behavior is covered. The description adds useful scope ('including all service components') but does not disclose additional behavioral traits such as caching, rate limits, or error behavior. Given the strong annotation coverage, a score of 3 is appropriate.

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

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

The description is a single, front-loaded sentence that directly states the purpose. No wasted words, and it is easy to parse. It earns every word.

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 parameterless status tool with no output schema, the description is complete. It tells the agent what the tool does and the scope of the health check, which is sufficient to decide when and how to 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?

The input schema has zero parameters, so the baseline is 4. The description does not need to explain parameters, and it correctly focuses on the tool's purpose. There is no ambiguity about how to invoke it.

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

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

The description clearly states the tool's function: 'Get the current health status of the Scalix Cloud platform including all service components.' It uses a specific verb ('Get') and a clear resource ('health status of the Scalix Cloud platform') with explicit scope, distinguishing it from sibling tools like scalix_usage or scalix_build_status.

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

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

The description provides clear context for when to use this tool (when you need the platform's health status). While it does not explicitly name alternatives or exclusions, the tool name and description make its purpose obvious, and no sibling tool directly competes for this specific information.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description does not contradict these. It adds important behavioral traits beyond annotations: bucket names must be unique within the project, and setting public=true makes every object readable without authentication. These are crucial side effects that go beyond the binary hints.

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, front-loaded with the primary purpose and followed by key details. Every sentence earns its place: the first states the action and object, the second explains uniqueness and public/private behavior. No redundant or 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?

For a simple two-parameter tool with no output schema, the description is complete. It covers the purpose, naming constraint, default behavior, and security implications. The annotations provide the safety profile, and the description covers the functional and contextual aspects needed for correct selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning for the 'public' parameter by explaining the default (false) and recommending presigned URLs for private sharing. This goes beyond the schema's field descriptions and clarifies the security implications.

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 and resource: 'Create a new Scalix Storage bucket in the project (S3-compatible object storage).' It is specific and distinguishes this tool from storage_upload/download/list by focusing on bucket creation. There is no sibling create_bucket tool, so the purpose is unambiguous.

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

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

The description provides clear context on when to use the tool (creating a bucket) and gives practical guidance on public vs. private sharing, including the recommendation to use presigned URLs for private sharing. It does not explicitly name alternatives or exclusions, but no alternative create-bucket sibling exists, so the context is sufficient for proper usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the return format (base64), which is useful behavioral context not present in annotations. It does not cover error handling, but the bar is lower given strong annotations.

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

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

Two short, front-loaded sentences with no filler. Every word contributes to the core purpose and return format.

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 two well-documented parameters, safety annotations, and no output schema, the description covers the core purpose and mentions the base64 return. It omits edge-case behaviors (e.g., missing keys) but is sufficient for a simple read-only download tool.

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

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

Schema description coverage is 100% for both bucket and key, so the description adds no parameter-specific meaning. The baseline 3 applies as the schema already does the heavy lifting.

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

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

The description uses a specific verb 'Download' with a clear resource 'object from storage', distinguishing it from sibling storage tools like upload or list. The note about base64 return further clarifies its unique purpose.

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 object content but does not explicitly mention when to prefer this over scalix_storage_list or scalix_storage_upload, nor any exclusions or prerequisites. It is adequate for an obvious use case but lacks explicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds the dual-mode behavior and prefix filtering, which is useful but doesn't disclose response format, pagination, or other operational details.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the tool's core behavior.

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 two optional parameters fully described in the schema and annotations covering safety, the description sufficiently defines the tool's scope. It doesn't explain return values, but this is a simple list operation and no output schema exists.

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 parameters. The description's mention of 'optional prefix filter' adds no new semantics beyond the schema's 'Filter objects by key prefix'.

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 (list), the resource (storage buckets/objects), and distinguishes between two modes: listing all buckets vs. objects in a specific bucket. This differentiates it from sibling tools like storage_upload and storage_download.

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

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

The description implies when to use it: without bucket for all buckets, with bucket for objects. It also mentions the optional prefix filter. It doesn't explicitly exclude alternatives, but the context is clear given the tool's role.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, indicating potential overwrites and idempotency. The description does not elaborate on these aspects, such as whether existing objects are overwritten, but it does not contradict the annotations either. It adds minimal behavioral context beyond the annotations.

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

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

The description is a single, directly worded sentence that states the core function and the key content format requirement. Every word earns its place with no redundancy or filler.

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

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

Given the moderate complexity of an upload operation and the presence of annotations (destructive, idempotent), the description is minimally sufficient but omits important details such as whether the bucket must already exist, behavior on overwriting, and return value. These gaps are partially mitigated by the annotations and schema, but a more complete description would include prerequisites and side effects.

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 complete descriptions for all four parameters (100% coverage), including the base64 encoding requirement for content. The description adds no new information beyond what the schema already states, so it scores at 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 identifies the action ('Upload') and resource ('object storage'), making it distinct from sibling tools like scalix_storage_download or scalix_storage_list. It 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 clear context for when to use the tool (uploading content to object storage) but does not explicitly mention when not to use it or reference alternatives. Sibling tool names help, but no direct exclusion or alternative is stated.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds minimal behavioral context, such as 'current' implying real-time data, but does not disclose additional traits like rate limits, authentication needs, or output size. This is adequate given the annotation coverage, but not exceptional.

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

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

The description is a single, front-loaded sentence with no filler. It efficiently communicates the essential purpose, which is appropriate for a tool with one parameter and no complex behavior.

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

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

The tool is simple (one required parameter, no output schema, no nested objects). However, without an output schema, the description should specify what constitutes 'usage metrics and costs' or what the response structure is. The current description is high-level and leaves room for ambiguity about the exact return data.

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 already provides a description for the sole parameter (project_id) with 100% coverage. The tool description does not add additional meaning about parameter format, allowed values, or relationships, so it relies on 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 tool's purpose with a specific verb ('Get'), resource ('usage metrics and costs'), and scope ('for a project'). It is easily distinguished from sibling tools like scalix_build_status or scalix_db_query, which serve different purposes.

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 no explicit guidance on when to use this tool versus alternatives, no prerequisites, and no exclusion criteria. It merely states what the tool does, so the agent receives no decision-making context beyond the purpose itself.

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