workspace-tools

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

With no annotations, the description carries the transparency burden. It adds the useful context that the api_key must be valid and comes from workspace configuration, implying authentication is required. However, it does not disclose side effects, destructive potential, or error behavior, leaving significant gaps.

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

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

The description is a single sentence, front-loaded with the core action. It includes a practical pointer to configuration. It is appropriately concise, though it sacrifices completeness for brevity.

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

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

While an output schema exists, the description fails to explain what 'administrative command' means, what commands are available, or how to construct the command string. There are two required parameters, but the command parameter is completely undocumented. The tool's behavior remains unclear beyond the auth requirement.

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

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

Schema coverage is 0%, so the description must compensate. It adds meaning to api_key ('valid api_key from workspace configuration') but says nothing about the command parameter, which remains vague. This is insufficient for a tool where command likely determines the entire operation.

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: 'Execute an administrative command.' It identifies a specific verb and resource, though it doesn't define what types of administrative commands are supported or differentiate itself from the sibling 'execute_command' tool beyond the 'admin' prefix.

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 a prerequisite ('Requires a valid api_key') but no guidance on when to use this tool versus alternatives like 'execute_command' or 'diagnostics'. There are no explicit exclusions or context about appropriate use cases.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It mentions requiring an api_key but does not state whether the operation is read-only, what outcomes are expected, or any side effects. This is insufficient for a tool with no annotation support.

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 of about 15 words, front-loading the main purpose. Every word contributes meaning; there is no redundancy or unnecessary detail.

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

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

The tool is simple, and an output schema exists, which may reduce the need to explain return values. However, the description lacks guidance on when to use this tool compared to siblings like diagnostics or admin_exec, and it does not clarify what 'pending items' means. Some 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 schema provides only the api_key parameter with no description (0% coverage). The description's parenthetical '(see workspace configuration)' adds useful context on where to find the key, partially compensating for the schema's lack of detail. However, it does not explain the api_key format or constraints.

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

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

The description clearly states the tool's function with a specific verb ('Check') and resource ('account access level and pending items'). It is unambiguous, though it does not explicitly differentiate from sibling tools like admin_exec or diagnostics.

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

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

The description implies usage when one needs to check access level or pending items, and it points to workspace configuration for the api_key. However, it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternative tools.

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

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

With no annotations, the description carries the full burden of explaining side effects, permissions, or return behavior. It only says 'internal diagnostic channel,' which is too vague to disclose what happens when invoked.

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 short and front-loaded, but it is under-specified to the point of being nearly uninformative. It earns no extra credit for brevity because the single sentence lacks substance.

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?

Even though the tool is simple (one required string parameter), the description fails to explain the handshake usage or what the diagnostic does. The output schema exists but cannot compensate for the absence of any behavioral or contextual explanation.

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

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

Schema coverage is 0% and the description does not mention the required 'report' parameter at all. The agent receives no help understanding what input is expected or how it affects the diagnostic output.

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 is a noun phrase that restates the tool's name ('diagnostic channel') rather than stating a specific action. It adds that it's used by the onboarding handshake, which gives some context, but the actual function remains unclear.

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 this is internal and tied to onboarding but never explicitly says when to use it or which sibling tools are alternatives. No concrete guidance is given for an agent deciding between diagnostics and other admin commands.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It only states that it executes a shell command and is admin-only; it does not mention side effects, reversibility, output behavior, or safety implications of running arbitrary commands, which is significant for a command execution tool.

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

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

The description is a single, compact sentence that is fully front-loaded and contains no unnecessary words. Every word contributes to the tool's purpose and access restriction.

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 that this is a powerful, potentially destructive command execution tool with no annotations and minimal description, the context is insufficient. It lacks usage guidance, behavioral disclosures, and parameter semantics, though the presence of an output schema helps somewhat.

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

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

The schema has only one parameter with no description (0% coverage). The description adds the meaning that the 'command' is a shell command, which clarifies the parameter type and purpose. However, it does not provide details like allowed values, syntax, or examples, so compensation is partial.

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 ('Execute') and resource ('shell command on the host'), and adds an admin-only qualifier. It is understandable, though it doesn't explicitly differentiate from sibling tools like 'admin_exec' which might overlap.

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, nor any exclusions or prerequisites beyond the 'admin only' restriction. There is no mention of when not to use it or which sibling tools might serve similar purposes.

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

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

With no annotations, the description must disclose behavioral traits. It reveals that the output includes sensitive secrets and connection strings, which is valuable. However, it does not mention auth requirements, side effects, or whether the operation is read-only (though 'Return' implies read-only).

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

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

One concise sentence with no wasted words, front-loaded with 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?

An output schema exists, so return values are documented. The tool takes no parameters and the description covers the essence. Slight lack of usage context, but overall sufficient.

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

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

The input schema has zero parameters, so there is nothing for the description to add beyond the schema. The baseline of 4 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 clearly states the tool returns server configuration and explicitly mentions secrets and connection strings, making its purpose specific. It does not explicitly contrast with sibling tools like list_credentials, but the resource is clearly defined.

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

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

No guidance is provided on when to use this tool versus alternatives such as list_credentials or diagnostics. There is no mention of exclusions or prerequisites.

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

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

With no annotations provided, the description must carry the burden of behavioral disclosure. It only says 'Fetch an additional page of results,' implying a read-only operation, but it does not mention error handling, page validation, or whether any state changes occur. This is minimal transparency for a tool with no 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, clear sentence with no wasted words. It effectively front-loads the core 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?

The tool is simple with one parameter and an output schema, so the description does not need to explain return values. However, it lacks critical details about how the 'page' parameter should be used and how it connects to the prior query, making it only marginally 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 has a single 'page' parameter with no description (0% schema description coverage). The description only says 'page of results,' which adds little beyond the parameter name. It does not clarify whether the page index is zero-based, what range is valid, or how it relates to page size.

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: 'Fetch an additional page of results from a prior paginated query.' This identifies a specific action (fetch) and resource (additional page of results), and it distinguishes the tool from sibling tools like query_database and search_documents, which likely initiate queries.

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 correct usage context: use this tool after a prior paginated query, not for starting a new query. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

No annotations are present, so the description must carry the full burden of behavioral disclosure. It indicates a 'List' operation (implying read-only) but fails to disclose sensitive aspects like the return of secret material, access control requirements, or any side effects. This is a significant omission for a credentials tool.

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

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

The description is a single, well-structured sentence that front-loads the action and object. No wasted words, and it is easily scannable.

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

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

Given the tool has zero parameters and an output schema exists (which should describe return values), the description is largely complete. It could mention that it lists all credentials or any security caveats, but these are not essential for a zero-argument list operation.

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

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

The input schema has zero parameters and 100% coverage, so there is no parameter information needed. The baseline for zero-parameter tools is 4, and the description correctly does not attempt to explain nonexistent 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') and a clear resource ('stored API credentials and access tokens for connected integrations'), making the tool's purpose immediately obvious. It also distinguishes itself from sibling tools, none of which mention credential 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?

No guidance is provided on when to use this tool versus alternatives. The description only states what it does, with no mention of exclusions, recommended contexts, or relationships to sibling tools like get_config or admin_status.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states 'read-only' which is a key safety trait, but it does not disclose what the query execution returns, whether results are paginated, or how errors are handled. The read-only attribute is already part of the purpose, so it adds no additional behavioral context beyond the purpose statement.

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 immediately states the verb and resource, making it highly concise while still conveying the core purpose.

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

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

The tool is simple with one self-explanatory parameter and an output schema, so the return format is presumably covered. However, the lack of usage guidelines or any behavioral details beyond 'read-only' leaves some gaps. It is adequate for a minimal query tool but not richly 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 0% and the description does not elaborate on the 'sql' parameter at all. It only says 'SQL query,' which weakly implies the parameter is the SQL text but does not explain syntax, dialect, size limits, or any other meaningful details. The description fails to compensate for the lack of parameter documentation.

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

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

The description clearly states the tool runs a read-only SQL query against the application database. The verb 'run' and resource 'SQL query' are specific, and the read-only qualifier distinguishes it from write operations. It is distinct from siblings like execute_command or read_file.

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

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

The description implies it is for read-only SQL queries but does not explicitly state when to use it over alternatives, nor does it mention any exclusions or prerequisites. There is no guidance on when not to use this tool, such as for data modifications or non-SQL tasks.

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

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

No annotations are provided, so the description must carry the transparency burden. It states the core read-only behavior, but does not disclose error handling (e.g., missing files), permissions, or path resolution nuances. It is adequate for a simple read operation but lacks extras.

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 efficiently conveys the tool's purpose and usage. Every word contributes value, 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 tool with one parameter, the description is nearly sufficient, but the example '/etc/...' contradicts the 'agent workspace' scope, leaving ambiguity about whether absolute paths outside the workspace are allowed. The output schema likely covers return values, but path navigation policy is unclear.

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 only defines 'path' as a string with no description, and schema coverage is 0%. The description compensates by giving examples ('./notes.md', '/etc/...') and clarifying the workspace context, adding meaning beyond the schema.

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

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

The description specifies a clear verb ('Read') and resource ('a file'), and defines the scope as the 'agent workspace' with example paths ('./notes.md', '/etc/...'). This distinguishes it from siblings like execute_command or get_config, 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 clear context for when to use the tool: reading files from the agent workspace by path. It does not explicitly mention alternatives or exclusions, but the single-purpose nature and examples make the intended use unambiguous.

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

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

There are no annotations provided, so the description must disclose behavioral traits. It describes the search action but omits critical details: whether the operation is read-only, what kind of results it returns, any rate limits, or auth requirements. The diagnostic handshake note adds some contextual insight, but it does not illuminate the tool's own behavior, leaving the agent underinformed.

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 appropriately concise, front-loaded with the core purpose in the first sentence. The diagnostic handshake note is a bit lengthy relative to the tool's function, but it conveys important onboarding context that earns its place. The structure is clear and does not waste 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?

Although there is an output schema (per signals), the description lacks essential context about the search behavior, parameter format, and tool-specific considerations. The diagnostic note is a generic prerequisite rather than complete guidance for this tool. For a simple search tool, the description could be adequate, but the missing parameter semantics and behavioral disclosure leave 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 input schema includes a single 'query' string parameter with no description, and the tool description does not explain the parameter at all. With schema description coverage at 0%, the description carries the full burden of explaining parameter semantics, and it completely fails to do so. The agent is left guessing what format or content is expected in 'query'.

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: 'Search the internal knowledge base and document store.' This specifies a verb (search) and a resource (knowledge base/document store), and it distinguishes from siblings like read_file (reading a specific file) and query_database (querying a database). However, it does not explicitly contrast with these alternatives, so it misses the top score.

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. The 'diagnostic handshake' note is a workspace-wide prerequisite, not a tool-specific usage guideline—it tells the agent to call diagnostics first, but never addresses when to choose search_documents over other tools. This lack of situational guidance results in a low score.

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