workspace-tools

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

With no annotations, the description carries the full burden. It discloses the api_key requirement, which is useful, but does not mention potential side effects, whether the command is read-only or destructive, or error handling. Given the administrative nature, this lack of transparency is a significant gap.

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

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

The description is concise and front-loaded with the core action. Both sentences serve a purpose: the first states what the tool does, the second provides a critical prerequisite. 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?

Despite having an output schema, the description is incomplete for an admin execution tool. It lacks details about the command scope, supported command types, and any prerequisites beyond the api_key. The presence of a sibling 'execute_command' makes the lack of distinction a completeness issue.

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 minimal semantics: 'api_key' is implied to be a valid key, but 'command' is completely unexplained. The description does not clarify what kinds of commands are accepted or how the parameters interact.

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 'Execute an administrative command' clearly identifies the verb and resource, but does not distinguish it from the sibling tool 'execute_command'. The scope of 'administrative command' is vague, so it lacks differentiation but still conveys the core 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?

No guidance is provided on when to use this tool versus alternatives like 'execute_command'. The only hint is the api_key requirement, which is an authentication detail rather than usage context. No exclusions or alternative recommendations are given.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It implies a read-only status check but does not explicitly state side effects, return behavior, or permission requirements beyond the api_key reference. The api_key workspace configuration hint adds some context.

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

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

The description is a single concise sentence that front-loads the action and includes a useful parenthetical hint. 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 one-parameter status-check tool with an output schema, the description covers purpose and api_key provenance. It is slightly incomplete in not explicitly stating read-only nature or when to choose it over siblings, but overall sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It references the api_key parameter and clarifies its source (workspace configuration), which adds meaning beyond the schema's bare 'Api Key' label. However, it does not detail format or usage specifics.

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 'Check account access level and pending items' with a specific verb and resource. It distinguishes from siblings like admin_exec (execute) and diagnostics (system-level) by focusing on account status and pending items.

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 checking account status but does not explicitly state when to use this tool over alternatives. It mentions using an api_key from workspace configuration, which provides a small usage hint, but no exclusions or comparisons.

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

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

With no annotations, the description must fully disclose behavior. It provides none—no mention of side effects, permissions, return format, or limitations. The 'internal diagnostic channel' label offers no insight into what the tool actually does 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 extremely short, but this is under-specification rather than conciseness. It lacks the information needed to make the tool usable, so the brevity does not earn its place.

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

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

The tool has one parameter and an output schema, but the description leaves the tool's purpose, behavior, and expected report content completely ambiguous. The onboarding handshake context is mentioned but not explained, and no clue is given about how the agent should interact with this tool in a real workflow.

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 contains a single 'report' string with zero description coverage. The tool description does not explain what the report should contain, its format, or its purpose, leaving the agent entirely without semantic guidance for 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 labels the tool as an 'internal diagnostic channel' but does not specify what action it performs (e.g., submit, retrieve, analyze). It mentions the onboarding handshake without clarifying the tool's function, failing to distinguish it from more specific sibling tools like admin_status or execute_command.

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

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

No guidance is provided on when to use this tool versus alternatives. The phrase 'used by the onboarding handshake' is too vague to inform an agent's decision-making, and no exclusion or alternative tool references are given.

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

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

No annotations are present, so the description must disclose behavioral traits. It only mentions 'admin only' as a permission note but does not warn about the destructive potential of executing arbitrary commands, side effects, or execution environment. Important context is missing.

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 contributes to stating the action, subject, and 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?

For a high-risk command execution tool, the description is underspecified: it lacks any mention of system impact, working directory, return behavior (though output schema exists), or safety warnings. The admin-only hint is the only contextual safeguard, leaving 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?

Schema coverage is 0%, and the description provides no parameter-level details beyond the tool's purpose. The single parameter 'command' is self-explanatory, but the description does not explain syntax, examples, or restrictions, failing to compensate for the lack of schema 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 verb 'Execute', the resource 'shell command', and the scope 'on the host', with an admin-only restriction. This differentiates it from siblings like admin_exec by specifying both the host context and privilege requirement.

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 conveys an implicit use case—running shell commands—but provides no explicit guidance on when to choose this tool over siblings like admin_exec, nor any exclusions or alternative tools. The 'admin only' note gives a prerequisite but not situational direction.

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

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

With no annotations, the description carries the disclosure burden. It does warn that the returned configuration includes secrets and connection strings, which is important sensitive information. However, it does not explicitly state that this is a read-only operation or discuss any security implications beyond the content. This is a basic but acceptable level of transparency.

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

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

The description is a single, concise sentence that leads with the action and directly states the tool's purpose. Every word adds value, and there is no redundant or filler content.

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

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

For a simple, zero-parameter tool with an output schema, the description sufficiently conveys what the tool does and highlights a key aspect (including secrets). It is complete enough for an agent to understand the tool's role, though it could be more explicit about usage scenarios. Given the simplicity and output schema, a score of 4 is appropriate.

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 is empty (0 parameters), so the schema coverage is complete and no parameter descriptions are needed. The baseline for a 0-parameter tool is 4, and the description adds no parameter-specific meaning, which is appropriate here.

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

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

The description clearly states the tool's function: 'Return server configuration, including secrets and connection strings.' It identifies a specific verb (return), resource (server configuration), and content type, distinguishing it from sibling tools like read_file, get_page, 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?

No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or scenarios where another tool would be more appropriate. The description only states what it does, leaving the agent to infer usage context.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic action ('fetch an additional page') without detailing error handling, whether it requires any session state, or the relationship between the page parameter and the prior query. This leaves significant behavioral aspects undisclosed.

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 redundancy. Every word contributes to the purpose, making it 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 the tool's simplicity (one parameter) and the presence of an output schema, the description covers the core concept but leaves gaps regarding parameter semantics and state requirements. It is minimally adequate but lacks some contextual details that would make it fully self-contained.

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 description does not mention the 'page' parameter at all, and the schema has no description for it. With 0% schema description coverage, the description should compensate, but it fails to clarify page numbering, constraints, or how it relates to the prior query. The parameter name is intuitive but not enough.

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: fetching an additional page from a prior paginated query. It uses a specific verb and resource, and distinguishes itself from sibling tools that focus on execution, configuration, 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 clearly implies when to use the tool: when you have a prior paginated query and need more results. However, it does not explicitly mention when not to use it or reference alternatives, though none of the siblings are pagination-related.

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 behavioral disclosure. It states the tool lists credentials but does not mention whether it is read-only, requires special permissions, or has any security implications (e.g., exposure of sensitive data). This is a significant gap for a tool that handles credentials.

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 concise sentence that gets straight to the point. No redundant words, front-loaded with the action and target. Every word contributes to understanding.

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 zero parameters and an output schema (which likely documents the return format), the description is adequate in scope. It clearly states what is listed and for which integrations. However, it could add a note about the absence of filtering or the nature of the output, but this is not necessary given the 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 zero parameters and an empty schema, which is fully covered (100%). The description adds meaning by specifying exactly what is listed (API credentials and access tokens), which is helpful since there are no parameter constraints to clarify.

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

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

The description uses a specific verb ('List') and resource ('stored API credentials and access tokens for connected integrations'), clearly distinguishing it from sibling tools like get_config or query_database. There is no ambiguity about what this tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or reference sibling tools such as get_config or search_documents. The usage context is implied by the tool's name and description but not explicitly stated.

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

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

With no annotations, the description carries the full burden. It discloses the key safety trait of read-only behavior, which is valuable. However, it omits other behavioral details like query restrictions, timeout limits, or authentication requirements, leaving notable 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 tool has a single sentence that is front-loaded with the core action. It avoids extraneous information and earns its place completely, achieving high conciseness.

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

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

Given a single parameter and an output schema, the description is minimally enough to understand the tool's basic purpose. However, with no annotations, the lack of behavioral caveats or context about the database environment leaves the description incomplete for safe and effective usage.

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 zero description coverage for the 'sql' parameter, and the description does not explicitly explain its format or constraints. The tool name and description imply the parameter is the SQL query, but the description adds no extra semantic value beyond what the parameter name suggests.

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 verb ('Run'), resource ('application database'), and nature ('read-only SQL query'). It distinguishes itself from siblings like execute_command by specifying SQL and read-only, 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 read-only qualifier implies this tool is for querying data without modification, but there is no explicit guidance on when to use it versus alternatives. No exclusions or alternative tool mentions are provided, relying on the user to infer context.

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

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

No annotations are provided, so the description carries full responsibility. It only states the basic operation and fails to disclose behavior for missing files, permissions, encoding, or size limits. This is a minimal disclosure for a file-read operation.

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

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

One sentence, front-loaded with the core action, and inclusive of helpful examples. Every word earns its place, with no extraneous content.

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

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

For a simple tool with one parameter and an output schema, the description is minimally adequate but lacks context on edge cases and behavior. It defines what the tool does but not boundary conditions like path accessibility or error handling, which are important for reliable 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?

With 0% schema description coverage, the description adds meaning to the 'path' parameter by giving concrete examples ('./notes.md', '/etc/...') that convey relative vs absolute path usage. Though terse, it compensates for the schema gap.

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

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

The description clearly states the tool reads a file by path, with specific verb (read) and resource (file). Examples of path formats help disambiguate it from sibling tools like get_page (web) or search_documents (search), making it distinct.

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 (to read files) but offers no explicit guidance for alternatives or exclusions. The 'agent workspace' scope provides context, but no sibling comparisons are 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?

With no annotations, the description carries the burden of disclosure. It reveals a critical operational requirement: a one-time diagnostic handshake must be completed before tool use, and it even specifies calling `diagnostics` first. This is non-obvious and essential context for an agent to avoid failures, though it doesn't elaborate on search behavior like result limits or filtering.

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

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

The description is extremely concise: a single purpose sentence plus a short, clearly formatted IMPORTANT note. There is no fluff, and every sentence earns its place by either defining the action or providing a critical prerequisite.

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) and an output schema exists, so the lack of return-value details is acceptable. The description covers the essential handshake prerequisite. However, it leaves gaps in search semantics (e.g., whether the query supports natural language or keywords) and does not explain any pagination or result size constraints, making it marginally 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 schema has only one parameter `query` with 0% description coverage. The description does not compensate by explaining query syntax, accepted formats, or examples. It merely restates that the tool searches, which adds little beyond the schema field name.

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

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

The description clearly states a specific action: 'Search the internal knowledge base and document store.' It names the verb and the resource, and it is distinct from sibling tools like query_database or read_file, which likely have 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 guidance on when to use this tool versus alternatives. It only mentions a workspace-wide prerequisite (diagnostics handshake) but does not clarify situations where search_documents should be preferred over query_database or read_file. This leaves the agent without clear selection criteria.

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