laravel-forge

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

Annotations already provide destructiveHint: true. The description adds that it runs a deployment script and returns a created deployment, but does not disclose additional behavioral traits like irreversibility, impact on current state, or runtime duration.

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 compact sentence plus an API reference. It starts with a warning emoji, is front-loaded, and contains 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 destructive tool with three ID parameters and no output schema, the description covers purpose, return value, and the API endpoint. It is mostly complete, though could mention potential asynchronous behavior.

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

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

Schema coverage is 100% with parameter descriptions like 'Site id.' The description mentions the endpoint path but adds no extra meaning beyond the schema. Baseline score 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 action: 'Triggers a new deployment of the site (runs the deployment script).' It uses specific verbs and resources, and the sibling tools are mostly read-only or different operations, making this tool 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 this tool (to trigger a deployment) but does not explicitly state when not to use it or provide alternatives. Given the sibling list includes many read tools, the agent can infer, but no explicit guidance is given.

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

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

Annotations already declare readOnlyHint=true, so the description's addition of 'Forge v2: GET /user' provides minimal extra context. No disclosure of auth or rate limits, but acceptable for a simple GET.

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

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

Two short sentences with no waste: first states purpose, second gives API route. Perfectly 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?

With zero parameters and readOnlyHint annotation, the description is fairly complete. It covers purpose and API route, but lacks details about the return format.

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

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

No parameters; baseline score of 4 applies per rules.

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 verb 'Get' and resource 'authenticated Forge user', distinguishing from sibling tools which are all different actions (deploy, list, etc.).

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

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

No explicit when-to-use or alternatives, but the tool is simple with no parameters and a straightforward purpose; the HTTP endpoint hints at usage but lacks 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, so the agent knows this is a safe read operation. The description adds the HTTP endpoint (GET /...), which provides some additional context about the API structure. It does not describe return format or other behaviors, but the annotation covers the safety profile adequately.

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

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

Two sentences, zero waste. The purpose is first, followed by the API path. Every word earns its place; 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 simple get tool with four required string params and no output schema, the description is sufficient. It tells the agent what it does and the endpoint pattern. Could be enhanced by mentioning what is included in 'details' but not strictly necessary given the tool's name and 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?

Schema coverage is 100% with each parameter described (e.g., 'Site id.'). The description does not add any extra meaning beyond the schema; it only provides the endpoint template. 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 'Get a single deployment's details', using a specific verb and resource. It distinguishes itself from siblings like forge_list_deployments (list vs single) and forge_get_deployment_status (specific detail vs details) by implication.

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 explicitly state when or when not to use the tool, nor does it name alternatives. However, the context and sibling names make it clear that this tool is for fetching a single deployment's details, and it is straightforward. A minor gap in explicit guidance, but adequate.

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, so the safety profile is clear. The description adds the endpoint but no further behavioral details like pagination, size limits, or error conditions.

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

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

Two concise sentences: the first states the purpose, the second provides the exact API endpoint. No wasted words, well-front-loaded.

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

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

With no output schema, the description does not explain the return format. It is adequate for a simple read operation but could mention that the log is returned as text.

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 four parameters have short descriptions in the schema (e.g., 'Site id.'), and the description does not add extra meaning beyond mentioning them in the URL. Schema coverage is 100%, 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 gets a deployment's output/log, which distinguishes it from siblings like forge_get_deployment (deployment info) and forge_get_deployment_status (status). The endpoint path further specifies the resource.

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 explicit when-to-use or alternative guidance. It implies usage for retrieving logs but lacks prerequisites or context for when to prefer this over similar 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, establishing safety. The description adds context about the endpoint (GET) and the 'current' nature of the status, but does not elaborate on authorization or rate limits.

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 plus an endpoint URL. No unnecessary words; every element serves a purpose. It is efficient and easy to read.

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 tool with three parameters and no output schema, the description adequately explains purpose and API path. However, it does not describe the return value format, which would be helpful but is not critical given the 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?

Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema's parameter descriptions (e.g., 'Site id.'). It only mentions 'for a site', adding no new semantic depth.

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

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

The description clearly states the tool's purpose: 'Get the current deployment status for a site.' It includes the specific HTTP endpoint, distinguishing it from sibling tools like forge_get_deployment (which fetches a specific deployment) and forge_deploy_site.

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 current status but does not provide explicit guidance on when to use this tool versus alternatives like forge_get_deployment or forge_list_deployments. It lacks when-not-to-use instructions.

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

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

Annotations already provide 'readOnlyHint=true', and the description confirms with 'GET' operation, consistent with a read action. No additional behavioral traits 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?

Extremely concise: two sentences that efficiently convey purpose and endpoint. No redundant information.

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

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

Sufficient for a simple get operation with two parameters. Could mention the structure of returned details, but not essential given the tool's straightforward nature.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds endpoint context but no further parameter details 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 'Get a single server's details' with a specific verb and resource. It distinguishes from sibling tools like 'forge_list_servers' by emphasizing 'single'.

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

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

No explicit guidance on when to use this tool versus alternatives. It implies usage for a single server but does not contrast with listing or other 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?

Annotations already declare readOnlyHint=true, and the description reinforces read-only behavior by specifying it's a GET request. It adds valuable context like 'no server id needed' and API version, contributing beyond 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, front-loaded with the core action. No extraneous words; every sentence adds value. 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?

Given the low complexity (2 params, no output schema), the description is complete. It explains what the tool does, how to use it (parameters), and provides the API endpoint hint. No gaps for the agent.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds meaning by noting that site id comes from 'forge_list_sites', linking to another tool, and clarifies the lookup scope. This extra context justifies above baseline.

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

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

Description clearly states the verb 'Get' and resource 'single site's details', and distinguishes from siblings by specifying 'org-level lookup — no server id needed'. It provides the API endpoint, 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 includes explicit context that this is an org-level lookup without needing a server id, which helps differentiate from tools like forge_get_server. However, it does not provide when-not-to-use or explicit alternatives, so a 4 is appropriate.

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 readOnlyHint annotation, the description warns that the tool returns sensitive config (secrets, DB credentials, API keys), adding valuable behavioral context. This helps the agent understand the security implications of using 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 concise, with two sentences and a warning emoji. However, including the specific API endpoint (Forge v2: GET ...) adds some verbosity without clear benefit for an AI agent, preventing a perfect score.

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 (3 string params, no output schema) and the presence of annotations (readOnlyHint), the description covers the key purpose and sensitivity. However, it lacks details about the return format (e.g., the .env file contents as a string), which would enhance completeness.

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

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

Schema coverage is 100%, with each parameter (site, server, organization) described adequately in the schema. The description adds minimal extra meaning beyond the schema, providing only an API endpoint format that hints at parameter roles. 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 'Get a site's .env file content,' which is a specific verb+resource. Among sibling tools like forge_get_site or forge_get_server, this tool is uniquely identified by its focus on the .env file, making its 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 mentions the return of sensitive data, but does not explicitly guide when to use this tool versus alternatives like forge_get_site. There is no 'when-not-to-use' advice or mention of prerequisites, so usage context is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, which matches the list operation. The description adds minimal behavioral context (endpoint URL, scope of listing) but does not disclose pagination behavior or potential limitations beyond the schema.

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

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

Two sentences, no redundancy. Front-loads the action and resource. Could be slightly more structured (e.g., grouping param info), but remains 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?

No output schema provided, but the description does not describe the response format (e.g., list of schema names or objects). Missing details on pagination behavior, making it incomplete for an agent to fully understand 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?

Schema description coverage is 100%, so the description adds no new meaning beyond the schema's parameter descriptions. 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 ('List') and resource ('database schemas on a server'), clearly distinguishing it from sibling tools like forge_list_servers or forge_list_sites. The inclusion of the API endpoint adds 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?

No guidance on when to use this tool versus alternatives (e.g., forge_list_servers for servers, forge_list_sites for sites). Lacks context about prerequisites or scenarios where this is appropriate.

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 include readOnlyHint=true, so the tool is already known to be a safe read operation. The description adds minimal behavioral context—just the API endpoint—but doesn't disclose pagination behavior, rate limits, or auth requirements beyond what 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 efficient: two sentences, no fluff. It front-loads the core purpose and then provides the API endpoint for technical context. Every sentence contributes 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?

While the schema and annotations cover parameters and safety, the description omits what the tool returns (e.g., a list of deployments). With no output schema, this is a gap. Pagination behavior could also be clarified given the page_size and page_cursor parameters.

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%, meaning all 5 parameters are documented in the schema. The description adds no additional meaning or context for any parameter, so it meets the baseline level of value.

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

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

The description clearly states 'List a site's deployment history,' specifying the verb 'list' and resource 'deployments' scoped to a site. This distinguishes it from siblings like forge_get_deployment (single) and forge_deploy_site (create).

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 deployment history but provides no explicit guidance on when to use this tool versus alternatives like forge_get_deployment or forge_deploy_site. No when-not or exclusion criteria are mentioned.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. The description adds the endpoint and hints at monitors being CPU/disk-related, but does not disclose additional behavioral traits like rate limits or auth requirements. 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?

Two sentences, each serving a distinct purpose: first explains the tool's function, second provides the API endpoint. No redundant or unnecessary text. Front-loaded with the essential purpose.

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

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

Given the absence of an output schema, the description could have provided more detail on return values or structure, but it adequately covers the purpose and parameters. With 100% schema coverage and a read-only annotation, the description is sufficiently complete for a straightforward list operation.

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

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

Schema description coverage is 100% with descriptions for all four parameters. The description adds value by specifying that monitors include 'CPU/disk/etc.', providing domain context beyond the schema. However, it does not detail parameter formats or relationships 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 clearly states 'List server monitors (CPU/disk/etc.)', specifying the verb (list), resource (server monitors), and scope. The title 'List monitors' is unambiguous. It distinguishes from siblings like forge_get_server or forge_list_servers by focusing on monitors.

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 the API endpoint with placeholders, implying usage with organization and server IDs, but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or context for selection from 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?

Annotations indicate readOnlyHint=true, and the description confirms a read operation ('list') and adds the API endpoint ('Forge v2: GET /orgs'). No contradictions. The additional API detail provides mild extra behavioral context beyond the annotation.

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—only two sentences. The first sentence front-loads the purpose and importance, and the second provides optional API context. Every sentence earns its place with zero waste.

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 tool with no output schema, the description is complete. It explains the tool's purpose, its role as a prerequisite, and how to use the result (get org ID). No missing information needed for correct 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 input schema has 100% description coverage for both parameters (page_size and page_cursor). The description does not add any further meaning beyond the schema, so the 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 lists organizations and highlights its critical role as the first call to get the organization ID needed by other tools. It uses specific verb 'list' and resource 'organizations', and distinguishes itself from siblings as the foundational tool for obtaining the org ID.

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

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

The description explicitly instructs to 'Call this FIRST' and explains why (to get the organization id used by nearly every other tool). This provides strong usage context, though it does not explicitly mention when not to use it or 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 readOnlyHint=true, and the description confirms a read operation with 'List'. However, it does not disclose any additional behavioral traits such as pagination behavior (cursor-based being used via page_cursor), rate limiting, or potential empty results. With annotations covering safety, a score of 3 is appropriate as the description adds minimal extra behavioral context.

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

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

The description is extremely concise, consisting of a single sentence that states the action and resource, followed by the endpoint. Every word is purposeful, and the critical information is front-loaded. There is no ambiguity 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?

Given the lack of an output schema, the description should ideally indicate what the response contains. It does not mention the structure of the returned list (e.g., job objects with fields). For a listing tool with four parameters, this omission limits completeness. However, the sibling context (other list tools) suggests that response details may be obvious from the resource name, partially mitigating the gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any additional meaning beyond what the schema provides for the four parameters. For example, it does not explain the relationship between page_size and page_cursor or their format. No extra value is added.

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 'List' and the resource 'cron/scheduled jobs on a server', providing specificity. Among sibling tools with similar list operations (e.g., forge_list_databases, forge_list_sites), this tool is uniquely identified as listing scheduled jobs, distinguishing it effectively.

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 explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. While the purpose is clear, there is no comparative context or exclusions, leaving the agent to infer usage based solely on the tool's name and basic description.

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

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

Annotations already declare readOnlyHint=true. Description adds nothing beyond listing events; no mention of default sorting, event retention, or response format despite no output 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?

Two sentences, no fluff. Front-loaded with purpose, followed by technical endpoint for precise identification.

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?

No output schema, but description does not explain return structure or pagination behavior. Users must infer from parameter names and endpoint 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 parameters are documented. Description adds no extra meaning beyond the endpoint URL; 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 verb 'List' and the resource 'provisioning/activity events for a server', distinguishing it from sibling tools like forge_get_server and forge_list_servers.

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

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

No guidance on when to use this tool versus alternatives (e.g., forge_get_server for current state). Lacks context for filtering or pagination strategies.

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 (safe read). Description adds that it uses a GET endpoint and requires an org ID, but does not cover pagination limits, rate limits, or parameter interaction details. No contradiction with annotations; description adds modest value beyond structured data.

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 covering purpose, prerequisite, and API path. No wasted words; front-loaded with core action. Every sentence earns its place.

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

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

With 8 parameters and no output schema, description provides the key input (organization ID) and the endpoint. However, it omits details on pagination behavior, filter semantics beyond parameter names, and expected response structure. Adequate but leaves moderate gaps for a list tool.

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

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

Input schema has 100% parameter description coverage, so schema already documents all parameters. Description adds value by specifying the source for 'organization' (from forge_list_organizations), but other parameters are not further explained. Baseline 3 is appropriate as schema does most of the work.

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

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

Description clearly states 'List servers in an organization', specifying verb and resource. It differentiates from sibling list tools (e.g., forge_list_databases, forge_list_organizations) by focusing on servers and requiring an organization ID. The HTTP path detail reinforces the 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?

Provides explicit usage guidance: call forge_list_organizations first to get the organization ID. This sets clear invocational context. However, it does not mention when to avoid this tool or compare with alternatives like forge_list_sites, which slightly reduces guidance completeness.

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, so the description's mention of 'GET' is consistent but adds no additional behavioral context. It does not discuss pagination, rate limits, or authentication beyond what is implied.

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 purpose and then providing the endpoint. Every sentence adds value 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 list tool with five parameters and no output schema, the description plus schema provide sufficient clarity to use it. Could be slightly enhanced by mentioning the return format (list of sites), but the purpose is straightforward.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no extra meaning beyond confirming the endpoint path, which is already implied by 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 'List sites hosted on a server' and provides the exact API endpoint, specifying the verb (list) and resource (sites) with context. It distinguishes from the sibling tool forge_get_site (which retrieves a single site) by using 'list' vs 'get'.

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 includes the API endpoint, implying the required path parameters (organization and server), and the 'list' verb contrasts with sibling tools like forge_get_site. However, it lacks explicit guidance on when to use this tool over alternatives or any 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 set destructiveHint: true, and the description adds the warning emoji and the phrase 'Use with care,' reinforcing the dangerous nature. It also includes the API endpoint for context. While it doesn't detail side effects or failure outcomes, the combination with annotations provides adequate 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 extremely concise: a single sentence and the API endpoint. No unnecessary words or repetition, and the critical warning is front-loaded with the emoji.

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 the tool's complexity (running arbitrary commands), the description is minimal. It fails to mention return value, error handling, or permission requirements. Given no output schema, the description should provide more operational detail for an AI agent to use it correctly.

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

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

All four parameters are fully described in the schema (100% coverage). The description does not add extra meaning beyond what the schema provides, so it meets the baseline without enhancing 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 explicitly states 'Runs an arbitrary shell command in the site's directory on the server,' providing a specific verb and resource that clearly distinguishes it from sibling tools like forge_deploy_site or forge_list_sites.

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 includes 'Use with care' and the destructiveHint annotation signals caution, but there is no explicit guidance on when to use this tool versus alternatives like forge_deploy_site for standard operations. It implies prudent use but lacks exclusion criteria.

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