Laravel Forge MCP by usefulapi

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

Annotations already declare destructiveHint=true, and the description is consistent with that, adding that it runs the deployment script and returns the created deployment object. However, it does not disclose whether the deployment is asynchronous, whether concurrent deploys are rejected, or what permissions are required - gaps that matter for a destructive trigger.

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

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

Three short sentences, front-loaded with a warning marker and the core action, then the return behavior, then the API endpoint. The endpoint line is mildly extraneous but cheap and aids orientation; nothing is buried.

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?

Return behavior is stated, which compensates for the absent output schema, and params are fully covered by the schema. It stops short of telling the agent how to track the deployment afterwards (forge_get_deployment_status / forge_get_deployment_log) or noting asynchronous completion, which are the remaining gaps for a destructive trigger tool.

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

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

Schema description coverage is 100% (all three required ids documented in-schema), so the baseline is 3. The description's REST path template reiterates organization/server/site as path parameters but adds no format, id-source, or validation detail 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 states a precise verb and resource: 'Triggers a new deployment of the site', clarified parenthetically as running the deployment script. That distinguishes it cleanly from the get_/list_ siblings, though it never names the one adjacent mutating sibling (forge_run_site_command) explicitly.

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

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

Usage is implied by the purpose (call it when you want a new deployment) but there is no explicit when-to-use guidance, no statement of prerequisites, and no comparison against forge_run_site_command or the status/deployment-reading siblings. An agent can infer the intent but gets no routing help.

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. The description adds nothing behavioral on top of that: no indication of auth requirements, what data is scoped to the caller, or rate limits. The REST endpoint reference is convention, not behavioral disclosure.

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

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

The primary clause is front-loaded and wastes no words. The second sentence ('Forge v2: GET /user') is redundant API trivia that occupies space without helping an agent decide or call, so it is not fully earned.

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

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

This is a simple zero-parameter getter, so complexity is low, and annotations cover the safety profile. However, with no output schema, the description does not indicate what the returned user object contains or how it is identified, leaving the return shape entirely to inference.

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 takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly does not invent parameter discussion.

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?

States a specific verb and resource: fetching the authenticated Forge user. This is clearly distinct from every sibling, which all operate on sites, servers, deployments, databases, or monitors. The trailing 'Forge v2: GET /user' is an API reference that adds no differentiation value.

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 about when this tool is appropriate, and no mention of prerequisites (e.g., that it requires an authenticated session) or alternatives. Because no sibling retrieves user identity, the omission is not misleading, but the description still provides zero routing 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 safety profile is covered. The description adds the Forge v2 REST endpoint (GET /orgs/{organization}/servers/{server}/sites/{site}/deployments/{deployment}), which helps correlate with API docs, but says nothing about auth requirements, error cases, or pagination behavior.

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

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

Two sentences, front-loaded with the purpose and followed by the endpoint mapping. Nothing wasted and no filler.

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

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

For a simple single-resource read tool with full schema coverage and readOnlyHint annotations, the description covers what is needed to select and call it. Return shape is unspecified and no output schema exists, but 'details' is a reasonable signal for a get-by-id call.

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 all four parameters are already documented in the schema, establishing a baseline of 3. The description's endpoint template loosely maps the four path params, adding marginal value but no syntax or format detail 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?

States a specific verb and resource: 'Get a single deployment's details', which is unambiguous. It doesn't explicitly differentiate itself from close siblings like forge_get_deployment_status or forge_get_deployment_log, but 'a single deployment's details' implicitly contrasts with the list/status/log variants.

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

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

Usage is implied by the name and the phrase 'a single deployment's details', but there is no explicit when-to-use guidance and no mention of when to prefer forge_get_deployment_status or forge_get_deployment_log instead. Adequate but with a clear gap.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds nothing beyond restating the purpose and the raw REST path — no indication of log size, truncation, tailing, or whether the log is complete or partial.

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 the purpose front-loaded and no filler. The API-path sentence is somewhat redundant for an agent but is compact and does not bloat the definition.

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?

A read-only GET with four fully documented required ids and no output schema — the essential shape is covered. Still missing context an agent would want: whether the log is truncated, how large it may be, and how it differs from the related status/deployment tools.

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

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

Schema description coverage is 100% with all four ids documented in the schema, so the baseline is 3. The description adds no syntax, format, or ordering hints 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?

States a specific verb and resource ('Get a deployment's output/log') and even pins the underlying Forge v2 endpoint. It distinguishes itself functionally from forge_get_deployment_status (status) and forge_get_deployment (metadata), though it never names those siblings explicitly.

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

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

Usage is implied by the resource: call this when you need the deployment's log output rather than its status or metadata. However, there is no explicit when-to-use/when-not guidance and no routing to the closely related sibling tools like forge_get_deployment_status or forge_get_deployment.

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?

readOnlyHint=true already establishes this is a safe read, and 'Get the current...' is consistent with that. The only added context is the underlying REST path, which is developer-facing rather than behavioral; it says nothing about what happens when no deployment exists or how fresh the status is.

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, purpose front-loaded, no padding. The second sentence is endpoint boilerplate that carries modest value for an API-aware agent, so it is not wasted but is not essential either.

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 three-required-parameter read tool with full schema coverage and a readOnlyHint, the core is covered. However, there is no output schema, and the description never hints at the shape or possible values of the returned status, which is the tool's entire payload.

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% - all three ids are documented in the schema, so the baseline is 3. The path template echoes organization/server/site but adds no semantics (e.g., id format or lookup source) 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?

States a specific verb and resource ('Get the current deployment status for a site'), which distinguishes it from siblings like forge_get_deployment and forge_get_deployment_log. It never explicitly contrasts those siblings, but the tool's scope is unambiguous.

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

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

No when-to-use guidance, prerequisites, or named alternatives. The description never explains how this differs from forge_get_deployment or forge_get_deployment_log, leaving the agent to infer selection from names alone.

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

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

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds the Forge v2 endpoint mapping (GET /orgs/{organization}/servers/{server}), which is useful context, but says nothing about what 'details' contains or error behavior.

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

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

Two tightly front-loaded sentences with zero filler: purpose first, endpoint provenance second. Nothing is wasted and the key action leads.

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?

There is no output schema, so the description carries the burden of telling the agent what is returned, yet 'details' is left undefined. Read safety is covered by annotations, but the lack of any return-value shape leaves a real gap for a retrieval tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters with source hints. The description adds only the endpoint template showing where organization and server map in the path, a marginal addition over structured data. 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 states a specific verb (Get) and resource (a single server's details), clearly distinguishing it from the bulk forge_list_servers sibling by emphasizing singularity. It does not, however, name the sibling or scope the retrieval further, so sibling differentiation is only implied.

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

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

Usage is only implied: 'a single server's details' suggests the singular counterpart to forge_list_servers, but there is no explicit when-to-use, when-not, or named alternative. An agent can infer the intent but must do the routing itself.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main addition is the Forge v2 endpoint mapping, which usefully anchors the operation to the underlying REST resource. It says nothing about missing-site behavior, permissions, or auth requirements 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?

Two tight sentences with the operation and its scoping front-loaded and the endpoint reference last; nothing is wasted and no reading is required to find the key constraint.

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 two-parameter read-only lookup with no output schema and full schema coverage, the description gives everything needed to select and invoke it. Only return-shape and not-found behavior are absent, which is minor against readOnlyHint.

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

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

Schema coverage is 100% and the schema already explains both parameters, including that the site id comes from forge_list_sites. The description reiterates the org scoping but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("Get a single site's details") and immediately scopes it as an org-level lookup needing no server id, which implicitly separates it from forge_list_sites and forge_get_server. It does not name a sibling explicitly, so this falls just short of the top band.

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 parenthetical "org-level lookup — no server id needed" implies when this tool applies rather than routing explicitly. No alternative is named and no when-not condition is given, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds meaningful context beyond that: the returned content is explicitly flagged as sensitive (secrets, DB credentials, API keys), which shapes how the agent should handle the result. It stops short of noting auth/permission requirements or output format.

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 compact sentences: the purpose is front-loaded, the sensitivity warning follows immediately, and the endpoint is a useful trailing detail. No 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 read-only tool with three fully documented required parameters and no output schema, the description covers purpose, sensitivity and endpoint. Only minor gaps (return format, error/permission behavior) remain.

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

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

Schema description coverage is 100%, with all three ids (organization, server, site) documented in the schema itself. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get a site's .env file content') and is clearly distinguishable from siblings like forge_get_site or forge_get_server. The Forge v2 endpoint reference further pins down exactly what it retrieves.

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

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

Usage is only implied by the security warning and the nature of the read; there is no explicit when-to-use statement or routing to alternatives (e.g. when to prefer forge_get_site vs this). Adequate but leaves selection to inference.

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 covered. The description adds the underlying API endpoint (GET /orgs/{organization}/servers/{server}/database/schemas), which is mild mechanical context, but says nothing about pagination behavior despite the presence of page_size/page_cursor parameters.

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

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

Two short sentences with the purpose front-loaded and no filler. The endpoint string is somewhat redundant with the tool's own identity but is compact and plausibly useful for callers who care about the underlying transport.

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

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

For a simple read-only list tool with an annotation covering safety and full schema documentation, the description is nearly complete. Only the pagination flow (cursor/size interaction, whether results are paged) is left entirely to the schema.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the page[size]/page[cursor] mappings. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline 3.

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

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

States a specific verb and resource ('List database schemas on a server'), which is unambiguous and distinguishable from the sibling list_* tools, none of which touch databases. It does not explicitly name the sibling it complements, so it stops short of a 5.

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

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

The description gives no when-to-use context, no prerequisites, and no mention of alternatives or how it relates to forge_list_servers or forge_list_sites. Usage is only implied by the purpose statement, which is the minimum guidance at best.

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?

readOnlyHint=true already establishes the safety profile, so the description's only added content is the raw v2 endpoint path. It says nothing about ordering, result limits, pagination behavior beyond the schema, auth/permission requirements, or rate limits — exactly the context an agent would need.

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, front-loaded with the action and scope. The endpoint string is arguably filler for an LLM agent, but it is compact and not confusing.

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 carries the burden of describing what a 'deployment history' entry contains and how to page through it; it does neither. No mention of ordering, default page size, or how results relate to the per-deployment siblings.

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%, including explicit notes that page_size maps to page[size] and page_cursor to page[cursor], so the schema carries the parameter semantics. The description adds no format or constraint detail beyond that, making the baseline 3 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?

States a specific verb+resource ('List a site's deployment history') and scopes it to a site, which is more precise than the title alone. It does not distinguish itself from close siblings like forge_get_deployment, forge_get_deployment_status, or forge_get_deployment_log, so an agent must infer the list-vs-single split.

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?

There is no when-to-use guidance and no mention of alternatives. The description never tells the agent to use this for enumerating deployments versus forge_get_deployment for fetching a specific one, nor does it mention prerequisites like needing a valid site/server.

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

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

The readOnlyHint=true annotation already establishes this is a safe, non-mutating read. The description adds the v2 endpoint path but says nothing about pagination behavior, result volume, or error/permission conditions beyond what annotations cover.

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, front-loaded with the operation and scope, with no filler. The trailing API-path sentence is mildly redundant for an agent but does not bloat the definition.

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?

A simple read-only list tool with full schema coverage and safety covered by annotations; there is no output schema to explain. The definition is sufficient to call it correctly, with only minor gaps around result shape and cursor semantics that the schema already handles.

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

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

Schema description coverage is 100%, and both required ids and the pagination params (page_size, page_cursor) are documented in the schema. The description adds no parameter meaning beyond what the schema already supplies, so the baseline 3 applies.

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

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

States a specific verb and resource ("List server monitors") with a clarifying example set (CPU/disk/etc.) and the underlying API path, so the agent knows exactly what is returned. It is distinguishable from siblings like forge_list_server_events or forge_list_servers by resource, though it does not explicitly contrast them.

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

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

The description gives no when-to-use, when-not-to-use, or alternative-tool guidance. It only names the operation and the REST endpoint, leaving the agent to infer selection from the resource name alone.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description adds the useful fact that the result feeds the org id into nearly every other tool. It says nothing about pagination behavior, though page_size/page_cursor exist, or about the shape of the returned list, so extra value beyond annotations is modest.

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

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

Three short, front-loaded sentences with the strongest guidance ('Call this FIRST') early. The trailing 'Forge v2: GET /orgs' is arguably noise for tool selection, but it does anchor the definition to a concrete API surface.

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

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

For a read-only, two-optional-parameter list tool with no output schema and full schema coverage, the definition covers what it returns and how to use it. The only real gap is pagination guidance for the two paging parameters, which the schema partially handles.

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 both parameters are fully documented in the schema, making 3 the baseline. The description adds nothing about pagination semantics such as when a cursor is needed or how large page_size may usefully be.

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?

States a specific verb and resource ('List organizations you belong to'), and adds scope ('you belong to') that distinguishes it from any general org-listing. No sibling covers organizations, so the agent can route unambiguously.

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

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

Explicit sequencing guidance: 'Call this FIRST to get the organization id used by nearly every other tool,' which tells the agent both when and why to use it. No when-not condition or alternative is named, but for a prerequisite-listing tool the context is effectively covered.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's burden is lighter. It adds the resource hierarchy via the endpoint (org-scoped, server-scoped), but says nothing about pagination behavior despite offering page_size and page_cursor — a real behavioral gap for a list endpoint.

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 filler; the purpose leads and the endpoint reference follows. Nothing is repeated and nothing is wasted.

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?

A simple read-only list tool with fully documented parameters and a clear scope, so the essentials are covered. But with no output schema, the description never hints at what the returned jobs look like or how to page through them, leaving the agent to infer the response entirely.

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 four parameters including the page[size]/page[cursor] mappings. The description adds nothing beyond that, which is the correct baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List cron/scheduled jobs on a server'), which unambiguously separates it from resource-specific siblings like forge_list_databases or forge_list_monitors. However, it never differentiates itself from any named sibling, which is the bar for a 5 under the rubric.

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?

There is no when-to-use or when-not-to-use guidance, and no alternatives are named. The Forge REST endpoint line is an implementation mapping, not usage guidance, so the agent gets only the implied 'use this to list scheduled jobs' signal.

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?

readOnlyHint=true already establishes this as a safe read. The description adds the API surface (GET /orgs/{organization}/servers/{server}/events) but says nothing about pagination behavior, volume of events, or ordering, despite the schema exposing cursor/page-size parameters.

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

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

Two compact sentences with the purpose front-loaded; the endpoint reference is short and only mildly redundant. Nothing is padded, though the second sentence is arguably incidental value for an agent.

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 read-only list tool with a fully documented schema and no output schema, the description covers the essential scope: what is listed and for which resource. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% — all four parameters (server, organization, page_size, page_cursor) are documented inline. The description adds no format or constraint details beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: 'List provisioning/activity events for a server.' An agent can distinguish this from the singular forge_get_server and the collection-level forge_list_servers. It does not explicitly name a sibling it is not, so it falls short of a 5.

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 when-to-use, when-not-to-use, or alternative tool is mentioned. The only usage signal is the REST endpoint mapping, which tells the agent how the call is implemented rather than when to choose it over sibling 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, so the safety profile is covered and the bar is lower. The description adds the dependency chain on forge_list_organizations and the underlying REST route, which is useful, but says nothing about pagination behavior even though page_size/page_cursor params exist.

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

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

Three short sentences, zero filler, with the primary action front-loaded followed by the prerequisite and the API route. Nothing redundant.

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 an 8-parameter read-only list tool with full schema coverage and no output schema, the description covers purpose, prerequisite, and endpoint, which is sufficient to invoke correctly. Minor gaps around pagination mechanics and result shape keep it from being exhaustive.

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

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

Schema description coverage is 100%, so every filter and pagination parameter is already documented, including its filter[...] mapping. The description adds no syntax, format, or default detail beyond that, making the baseline 3 correct.

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?

States a specific verb and resource with scope ('List servers in an organization'), which an agent can distinguish from forge_get_server (single server) and forge_list_sites. It does not explicitly name sibling alternatives, but the scope qualifier is enough to identify the tool.

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?

Gives a concrete prerequisite ordering: call forge_list_organizations first to obtain the organization id. That is real when-to-use guidance. It stops short of stating when to prefer forge_get_server or how to page through results.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds only the Forge v2 endpoint mapping, which is context but not behavioral disclosure, and says nothing about pagination behavior despite page_size and page_cursor existing.

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, zero waste, with the core purpose front-loaded and the API reference relegated to a secondary clause. Every element earns its place.

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

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

For a read-only list tool with a fully documented schema and annotations covering safety, the description is nearly sufficient. The only real gap is that pagination cursor behavior is left entirely to the schema, which is acceptable since no output schema exists to conflict.

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 both required and optional parameters (including the filter[name] and page[...] mappings) are already documented in the schema. The description adds no parameter syntax or semantics beyond what the schema provides, making the baseline 3 correct.

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?

States a specific verb (list) and resource (sites) plus the scoping constraint (hosted on a server), which cleanly separates it from the singular sibling forge_get_site. It does not explicitly name siblings, but the singular/plural distinction is unambiguous.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as forge_get_site for a single site or forge_list_servers for the parent resource. Only the most obvious usage is implied by the 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 destructiveHint=true, so the risk profile is partly covered. The description adds genuinely useful context beyond that: the command is arbitrary, it executes on the server, and it runs in the site's working directory. It does not disclose permissions required, whether execution is synchronous, how output/failure is surfaced, or any 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?

Front-loaded with the warning and the core action in a single tight sentence, with the caution adjacent. The trailing 'Forge v2: POST /orgs/...' endpoint is implementation detail that consumes space without helping an agent decide or invoke, keeping it short of a 5.

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

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

For a destructive, arbitrary-command tool with no output schema and annotations covering only destructiveness, the description covers the essentials (what runs, where, with a caution) but omits what comes back, whether the call blocks, and how failures are reported. Adequate but with clear 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 description coverage is 100% with all four params documented, including an example command, so the schema carries the load. The description adds only the REST path showing how organization/server/site/command map to URL segments, which is marginal. Baseline 3 per the coverage rule.

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?

States a specific verb (Runs), resource (an arbitrary shell command), and scope (in the site's directory on the server). No sibling in the list executes commands, so the agent can distinguish it immediately from forge_deploy_site and the get_* tools.

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

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

Only guidance is the generic warning 'Use with care.' There is no statement of when this is the right tool versus forge_deploy_site or forge_get_deployment_log, nor any exclusion about when not to use it. The caution flags risk but does not route the agent.

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