Codebase

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

With no annotations, the description carries the full behavioral burden. It implies mutation ('Create') and a generative prompt input, but discloses nothing about side effects, authentication needs, reversibility, or what 'shell' produces versus a built project.

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

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

A single tight sentence with the action front-loaded and zero filler. It is efficient, though its brevity reflects under-specification rather than deliberate economy.

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 mutation tool with no annotations, no output schema, and 0% parameter coverage, the description is far too thin. An agent cannot tell what the returned project shell contains, what happens next, or how the two parameters behave.

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

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

Schema coverage is 0% and neither parameter is documented in the schema. The description only implies the 'prompt' parameter ('from a prompt') and says nothing about 'model', leaving the agent to guess its meaning and valid values.

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

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

States a specific verb ('Create') and resource ('Codebase project shell'), which clearly distinguishes it from read-oriented siblings like codebase_get_project and codebase_list_projects. The term 'shell' is slightly opaque (does it scaffold empty files, or generate code from the prompt?), but the core action 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 and no mention of alternatives or prerequisites, despite siblings like codebase_start_build and codebase_deploy that an agent would need to sequence after creation. The agent must infer that this is the entry point for a new project.

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

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

With no annotations, the description carries the full burden and does well: it discloses the asynchronous contract, the immediate response shape ({ deployId, status: "building", poll }), the background build duration, and the follow-up polling requirement. It omits auth/permission requirements and any note about failure/reversibility.

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 core action is front-loaded and every sentence adds information about async behavior or tool chaining. The middle clauses about the hosted URL and response payload make it slightly dense/run-on, but there is 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?

No output schema exists, and the description helpfully covers the return shape and the polling loop, which is what an agent most needs. However, for a 4-parameter tool with a nested object and zero schema coverage, leaving name and target undocumented is a real gap, and no output/error semantics beyond "ready or error" are given.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does. It clarifies provider="codebase" behavior (hosted site at <projectId>.codebase.guru) and implies projectId semantics, but the "name" and "target" parameters are never mentioned or explained despite target being a nested object.

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 ("Start a deployment for a built Codebase project") and qualifies the input as an already-built project, which distinguishes it from codebase_start_build. It does not explicitly contrast itself with siblings like codebase_publish or codebase_rollback_deploy, but the action 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?

Gives clear operational guidance: the call returns immediately and the caller must poll codebase_get_deploy_status until ready or error, and it notes the deployId works with codebase_rollback_deploy. It stops short of stating when to choose this over publish or start_build, but the implied workflow is well 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?

With no annotations, the description carries the full burden; it usefully discloses reuse behavior (idempotent-ish start) and the nature of what is returned (a private link for a human). It does not state auth/permission needs, whether the preview consumes credits, or what happens if the build doesn't 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?

One sentence, front-loaded with the action and followed by the returned URLs; every clause carries information. Slightly run-on but no 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?

Because there is no output schema, the description usefully enumerates the return values (previewUrl, workspaceUrl, sourceUrl), which is a real contribution. The gap is the undocumented sessionId input, leaving the calling contract partially unclear.

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

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

Schema coverage is 0% and the single required parameter (sessionId) is never mentioned in the description. The description does not explain what a session id is or where to obtain it, so it fails to compensate for the documentation gap.

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

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

The description gives a specific verb+resource ('Start (or reuse) the live preview for a build') and names the return artifacts. It distinguishes itself from build-lifecycle siblings like codebase_start_build and codebase_get_build_status by focusing on the preview link, though it never names those alternatives 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?

The parenthetical '(or reuse)' implies this is safe to call when a preview may already exist, which is useful implicit guidance. However, there is no explicit when-to-use vs alternatives, no prerequisites, and no statement of when this should be called relative to codebase_start_build or codebase_get_build_status.

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

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

No annotations are provided, so the description carries the full burden and largely delivers: it discloses the short-lived token on previewUrl, the previewExpiresAt expiry requiring re-polling, and the failure shape with a retryable flag. This is substantial behavioral context beyond the bare 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?

Front-loads the action (poll status) and then enumerates key return fields efficiently. The single long sentence is dense but every clause names a concrete field the agent must relay, so little 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?

For a polling tool with no output schema and no annotations, the description compensates well by naming each result field (summary, previewUrl, workspaceUrl, sourceUrl, failure) and the token/expiry lifecycle. An agent has enough to poll, relay, and handle failure correctly.

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

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

Schema description coverage is 0% for sessionId, and the description doesn't explain what a sessionId is or where to obtain it (presumably from codebase_start_build). Baseline for one required param with no schema docs is 3; more guidance on sourcing the sessionId would push this higher.

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 (poll) and resource (build session status) with explicit scoping to an existing session. An agent can immediately distinguish this from codebase_start_build, codebase_get_build_preview, and codebase_get_deploy_status based on the description alone.

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?

Clear contextual routing: 'Once the build ends, hand the result to your human' and the previewExpiresAt polling loop tell the agent when and how to re-invoke. However, no explicit mention of codebase_get_build_preview as the alternative for preview-specific fetching, so sibling differentiation is implied rather than named.

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

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

No annotations are provided, so the description carries the burden, but 'Read' plus 'current balance' does convey a non-mutating, point-in-time query with no side effects. It omits auth requirements, rate limits, and whether the balance is account- or project-scoped, which for a billing-related read would be useful 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?

A single front-loaded sentence with no filler; every word earns its place. Appropriate size for a zero-argument 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?

With no annotations and no output schema, the description is the only source of information, and it does not describe the return shape (units, currency, formatting) or how it relates to codebase_get_usage. For a trivial zero-param read this is close to adequate, but the sibling ambiguity and missing return context leave gaps.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. No additional parameter semantics are needed or missing.

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 ('Read') and resource ('the current Codebase credit balance'), so the agent knows exactly what it returns. It does not differentiate itself from the sibling codebase_get_usage, which is a plausible alternative for similar billing/quota information.

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 guidance on when to use this tool versus codebase_get_usage or any other sibling, and no stated prerequisites. The agent must infer the use case purely from the tool name.

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

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

With no annotations, the description carries the full burden and does well: it enumerates the status values, maps "ready" to a live url, lists error codes (BUILD_FAILED, LAUNCH_CHECKS_FAILED, interrupted) plus a readable message, and specifies the polling cadence. It omits any note on auth requirements, rate limits, or how long to keep polling before giving up, which keeps it short of a 5.

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 compact clauses, front-loaded with the action, then the polling instruction, then the outcome semantics. No filler sentences and no repetition of the name or schema fields.

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 and no annotations, so the description must explain results itself, and it does: status values, error codes, message, and url are all covered. Only the polling lifecycle edge cases (timeout, backoff, terminal conditions other than ready/error) are left unaddressed.

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

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

Schema description coverage is 0%, so the two parameters are undocumented structurally. The description compensates only partially: it implies deployId is the handle obtained from codebase_deploy, but never states the expected format, and it says nothing about the provider enum or why one of the five values must be supplied.

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: poll the current status of an existing deployment, with concrete return states (ready/error/building). It does not explicitly distinguish itself from the sibling codebase_get_build_status, but the deployment-vs-build framing and the deployId parameter make the target unambiguous in practice.

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 explicit when-to-use: call every few seconds after codebase_deploy, and continue while status is "building"; stop at "ready" or "error". This names the triggering sibling tool and both terminating and non-terminating conditions, leaving nothing 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?

No annotations provided, so the description carries the full burden. It discloses the encoding constraint (UTF-8), which is useful, but nothing about error behavior for missing files, binary files, permissions, or return 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?

One concise, front-loaded sentence with no waste. Appropriate size for the tool's simplicity.

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

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

For a file-read tool with two undocumented required parameters, zero annotations, and no output schema, the description is too thin. It should at least clarify path semantics (absolute vs relative to project root) and error 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 description coverage is 0% – neither projectId nor path are documented in the schema. The description says nothing about what projectId or path mean, whether path is relative to project root, or format expectations. Fails to compensate for the coverage gap.

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

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

States a specific verb+resource: 'Read a UTF-8 text file from a Codebase project.' Clear and distinct from siblings like codebase_list_files. Doesn't explicitly differentiate beyond the obvious read-file semantics.

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 vs codebase_list_files or other alternatives. Just describes what it does, not when to reach for it.

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

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

With no annotations, the description carries the full behavioral burden. It does usefully disclose the returned surface (previewUrl, workspaceUrl, sourceUrl, last build's failure), which is valuable since there is no output schema. However, it never states that this is a non-mutating read, nor any auth/permission requirement.

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

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

A single sentence, front-loaded with the core action and then the useful return payload. It is slightly run-on with the appended 'to hand to your human' clause, but there is 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?

Given one param, no annotations, and no output schema, naming the return fields is a meaningful compensation for the missing output schema. But the sole parameter is entirely unexplained, which leaves a real gap for an agent that does not already know how to source a projectId.

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?

There is one required parameter, projectId, and the description never mentions it. Schema description coverage is 0%, so the description had room to add meaning and does not — it gives no hint about where to obtain a projectId or its expected format.

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 and resource: 'Get details for a Codebase project.' This clearly distinguishes it from codebase_list_projects and the build/deploy siblings. It stops short of explicitly naming which sibling to use instead, so it lands at a solid 4 rather than 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?

Usage is implied by the verb and by 'to hand to your human,' which hints at the human-facing context. But it never says when to reach for this versus codebase_list_projects or codebase_get_build_status, and no prerequisites are stated. This is minimum-viable 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that results are paginated and scoped to the current identity, but says nothing about ordering, result window, rate limits, or auth requirements. For a read-only listing tool this is passable but thin.

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

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

A single front-loaded sentence with no filler; the resource and scope come immediately. It is efficient, though arguably it could spend another clause on the sibling distinction without becoming bloated.

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 listing tool with no output schema, the description covers the basics but omits what a usage entry contains and how this differs from codebase_get_credits. With two parameters undocumented and no annotations, the definition is minimally viable rather than complete.

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

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

Schema coverage is 0% with two undocumented parameters (limit, offset). The word 'paginated' hints that pagination parameters exist, but the description does not explain the offset/limit semantics, the maximum of 200, ordering, or defaults, so it fails to compensate for the coverage gap.

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

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

The description states a clear verb ('Read') and resource ('credit usage history') with an explicit scope ('for the current identity'), so an agent knows what it returns. However, it never differentiates itself from the obvious sibling codebase_get_credits, leaving ambiguity about which credit-related tool to pick.

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 guidance about when to use this tool versus codebase_get_credits, nor any mention of prerequisites or context. The agent must infer usage purely from the name, which is risky given two credit-related 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?

No annotations are provided, so the description carries the full behavioral burden. 'Read' implies a non-mutating operation, but there is no disclosure of auth requirements, what the checks actually cover, output shape, or any rate/aggregation 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?

A single front-loaded sentence with no filler. It is efficient, though its brevity is partly the source of the gaps elsewhere.

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 and no annotations, the description should hint at what the health/dependency result contains. It gestures at 'aggregate health and dependency checks' but does not specify what is returned, leaving the agent to call blind.

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 there is nothing for the description to disambiguate. Baseline 4 applies.

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

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

States a specific verb (Read) and resource (aggregate Codebase platform health and dependency checks), so an agent can tell it apart from the status/usage siblings like codebase_get_build_status or codebase_get_usage. It is not a tautology, though 'aggregate' is slightly vague about scope.

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 or when-not-to-use guidance, and no alternatives named. Nothing tells the agent whether this is a pre-flight check, a diagnostic, or a substitute for codebase_get_credits/get_usage.

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

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

With no annotations, the description carries the full burden. It usefully discloses result ordering (newest first) and the meaning of the 'live' field, but says nothing about pagination, how 'limit' is applied or defaulted, or what happens when a project has no deploys.

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, no filler, with the core purpose front-loaded before the supplementary 'live: true' detail. Every clause 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 simple two-parameter list tool with no output schema, the description covers purpose, ordering, and one result field. It is still missing limit/pagination semantics and any indication of what a deployment record otherwise contains, which matters given 0% schema coverage and no annotations.

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

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

Schema description coverage is 0% and neither parameter is documented. 'projectId' is only obliquely implied by 'a project's deployments', and 'limit' (integer, 1-50) is entirely absent from the description, leaving an agent to guess at its meaning and defaults.

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 names a specific verb and resource ('List a project's deployments') and adds ordering ('newest first'), so an agent can separate it from the singular status tools like codebase_get_deploy_status. It never explicitly names a sibling or an exclusion, so it stops short of full differentiation.

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: the reader infers this is the tool for browsing deployment history, and the 'live: true' note hints at how to identify the currently-served deploy. There is no statement of when to prefer this over codebase_get_deploy_status or codebase_rollback_deploy.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not disclose whether the listing is recursive or flat, whether it is paginated, whether auth or scope restrictions apply, or how many entries might be returned. For a read tool with zero annotation coverage, this leaves major gaps.

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

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

A single short sentence with no waste. It is appropriately sized but nearly content-free, so conciseness comes at the cost of substance.

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

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

With two parameters, 0% schema coverage, no annotations, and no output schema, the description is far too thin. An agent lacks enough information about scope, recursion, and parameter meaning to invoke the tool reliably in a codebase toolchain with many 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 0%, and the description only vaguely implies a project directory. Neither 'projectId' nor 'path' is explained: what a projectId references, whether path is relative to the project root, or whether null/empty path defaults to root.

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 clear verb+resource ('List files') with a scoping context ('in a project directory'). It distinguishes from sibling codebase_get_file (single file retrieval), though it doesn't explicitly name that sibling.

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, no alternatives mentioned, and no exclusions. An agent could infer it lists files, but nothing tells it whether recursion, depth, or hidden-file behavior applies, nor points to codebase_get_file for single-file reads.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Browse' weakly implies a read-only operation, but nothing is said about pagination, ordering, result caps, or whether the gallery requires authentication or covers only public projects. For a listing endpoint with limit/cursor semantics, that is a real gap.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient as far as it goes; the brevity stems from under-specification rather than from tight editing of complete content.

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

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

With no annotations, no output schema, and undocumented parameters, the description is the only source of guidance, and it leaves pagination, ordering, and result shape entirely unexplained. A list tool with limit/cursor parameters needs far more than one sentence.

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

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

All three parameters (sort, limit, cursor) have 0% schema description coverage and the description mentions none of them. It does not explain accepted sort values, the limit ceiling, or how cursor-based paging works, so the agent must guess at every argument.

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 concrete verb ('Browse') and a specific resource ('published Codebase gallery projects'), so the agent knows this is a read of the public gallery. It implicitly separates itself from codebase_list_projects (published gallery vs. presumably the caller's own projects), though it never names that sibling to make the distinction explicit.

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

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

No when-to-use condition, no prerequisites, and no mention of the adjacent listing tools (codebase_list_projects, codebase_list_deploys) that an agent must choose between. 'Browse' is the only usage signal, and it is implied rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' strongly implies a non-mutating read, but the description does not explicitly state read-only behavior, authentication requirements, or whether results are static or account-scoped.

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

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

A single short sentence, front-loaded with the verb and the most important resource. No filler or redundancy; every word earns its place.

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

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

For a zero-parameter read tool with no output schema, the description names the three categories of information returned, which is enough for an agent to understand the result surface. It could go slightly further by stating read-only nature and account scoping.

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 there are no parameter semantics to convey and the baseline of 4 applies. Schema coverage is 100% and empty, making the description's enumeration of returned content the only useful semantics.

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 enumerates the resources returned: Codebase models, providers, and the current default model. This is clearly distinct from sibling list tools such as list_projects, list_deploys, and list_files, though it does not explicitly name 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?

There is no guidance on when to call this tool, what precondition applies, or which alternative to prefer. Usage is only implied by the verb 'List'; nothing tells the agent whether this is for discovery before deploying, for confirming a default provider, etc.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only listing scoped to the caller's identity, but says nothing about pagination, result ordering, or what happens when the identity owns many projects. For a schema with limit/offset offsets this is a notable gap.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though its brevity is partly under-specification rather than disciplined conciseness.

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

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

For a simple list tool with no output schema and no annotations, the description covers the core operation and scope, and return values need not be explained. However, pagination behavior for the two declared parameters is missing, leaving the definition thin where it matters.

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

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

Schema description coverage is 0% and neither 'limit' nor 'offset' is mentioned in the description, so the pagination contract (defaults, max 100, whether offset is zero-based) is left entirely undocumented. The parameters are conventional enough to guess, but the description adds no meaning over the raw 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 ('List') and resource ('projects') and adds a scoping qualifier ('owned by the current Codebase identity'), which distinguishes it from codebase_get_project (singular) and the many other list_* siblings. It does not name any sibling explicitly, but the resource noun plus scope makes the intent 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 guidance, no mention of prerequisites or alternatives (e.g. codebase_get_project for a single project), and no indication of how to page through results. Usage is only inferable from the name.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that the effect is gallery-listing only and not deployment/hosting, which clarifies the mutation's blast radius. However, it says nothing about reversibility (unpublish), permission/auth requirements, credit consumption, or what happens to an already-listed project.

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 core action front-loaded and the disambiguation second. No filler, 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 mutation tool with no annotations, no output schema, and 0% schema description coverage, the description answers 'what' and 'not what' but leaves all four parameters and the reversal path (codebase_unpublish) undocumented. An agent can route correctly but not call it confidently.

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

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

Schema description coverage is 0% across 4 parameters (projectId, title, description, tags), and the description names none of them. The word 'List' only faintly implies that title/description/tags are public-listing metadata; required projectId, tag limits, and length constraints are left entirely to 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 action on a specific resource (listing an owned Codebase project in the public gallery) and makes the scope clear ('owned'). It differentiates itself from codebase_deploy, though it does not contrast with the closely related codebase_unpublish or codebase_list_gallery.

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

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

Explicitly names a case this tool does NOT cover and routes the agent to the right alternative ('this does not deploy or host the site (use codebase_deploy)'). It lacks guidance on prerequisites (ownership/auth) and on the reverse operation codebase_unpublish, so it stops short of full when/when-not coverage.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the retention window (live + last ten) and that the rollback is recorded as a new deploy, which are non-obvious behaviors. However it omits permission requirements, reversibility, and what happens to the prior live deploy.

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

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

A single efficient sentence pair with the key constraint (ready, retained) front-loaded 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 one-param mutation tool with no annotations and no output schema, the description covers the core behavior and eligibility but leaves gaps around auth, reversibility, and return value. Adequate but not complete.

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

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

Schema description coverage is 0% and deployId is undocumented in the schema. The description implies deployId must reference an earlier ready deploy and mentions the retention window, which adds real meaning. But it doesn't state the ID format or how to obtain a valid deployId.

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?

Clear verb 'roll back' plus specific resource 'Codebase-hosted site' to an earlier ready deploy. Distinct action from siblings like codebase_deploy or codebase_publish, though it doesn't explicitly name an alternative 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?

The parenthetical clarifies which deploys are eligible ('ready', 'live one and last ten'), implicitly guiding selection of deployId. But there is no explicit when-to-use versus alternatives like codebase_deploy or codebase_list_deploys for finding a valid deployId.

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

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

With no annotations, the description carries full disclosure burden and does well on the important traits: it is asynchronous (returns a session ID to poll), idempotent, and explicitly notes that a repeated call avoids 'charging for' a second build. It still omits auth requirements, failure behavior, and 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?

Three sentences, front-loaded with the core action and return value, then the idempotency caution, then the scaffold/recipe detail. The final sentence is dense but every clause carries actionable content; 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 6-parameter tool with no annotations and no output schema, the description covers the lifecycle entry point, idempotency, and the Base scaffold path, and it does state the return value. However it leaves model/projectId unexplained and says nothing about what a build actually produces or how long it takes.

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

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

Schema coverage is 0%, so the description must compensate. It explains three of six parameters well (idempotencyKey semantics, scaffold 'scaffold-base', and recipe with meanings for payments/social/game/mint), but leaves model, projectId, and prompt entirely undocumented.

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 ('Trigger a Codebase build') plus a concrete outcome ('return a session ID for polling'), which clearly separates it from status/stop/preview siblings. It does not name any sibling explicitly, 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?

Gives clear conditional guidance: use the same idempotencyKey when retrying, and pass scaffold 'scaffold-base' with a recipe for Base onchain apps. It supplies context for two usage paths but names no alternatives or when-not conditions relative to siblings like codebase_deploy or codebase_get_build_status.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says 'Cancel' but does not state whether cancellation is reversible, what happens to partial build artifacts, whether it errors on a finished session, or what permissions are required — significant gaps for a mutation 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?

One short, front-loaded sentence with no filler — the verb and object lead immediately. It is efficient, though the extreme brevity leaves the substance thin rather than merely tight.

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 mutation tool with no annotations, no output schema, and an undocumented required parameter, the description is too thin. It omits prerequisites, the source of the session ID, error behavior, and the result of a successful cancellation.

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

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

The single parameter sessionId has 0% schema description coverage, so the description must compensate and does not. It never explains what a session ID is, where the agent obtains one (e.g. from codebase_start_build or codebase_get_build_status), or the expected format.

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 names a specific verb ('Cancel') and resource ('an active Codebase build session'), which cleanly separates it from siblings such as codebase_start_build and codebase_rollback_deploy. It is clear on its own, but it never explicitly names the sibling it complements or the counterpart it undoes.

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 word 'active' implies the tool applies only to in-flight builds, which is a usable hint. However, there is no explicit when-to-use guidance, no statement of what to do for a queued or already-completed build, and no reference to any alternative tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses a genuinely non-obvious behavioral fact – that removal affects only the gallery and does not take the hosted site offline – but omits permissions/ownership requirements and reversibility (whether it can be re-published).

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 zero filler; the scope statement is front-loaded and the disambiguation follows immediately.

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

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

For a single-parameter mutation with no annotations and no output schema, the description covers the essential scope and sibling disambiguation. It stops short of stating required ownership/permissions, which is the main remaining unknown for an agent about to call it.

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

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

The single parameter projectId has 0% schema description coverage and is never mentioned in the description. The name is largely self-evident and the schema enforces minLength 1, so the gap is mild, but the description adds nothing about accepted ID format or source.

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 (Remove), resource (owned Codebase project), and scope (from the public gallery), which cleanly separates it from codebase_publish. The agent can identify the exact effect without opening the schema.

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

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

Explicitly names the boundary condition ('Gallery only') and routes the agent to the correct alternative ('use codebase_unpublish_site') for taking a hosted site offline. When-not and alternative are both stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses the destructive effect (404), what is preserved (deploy files), how to reverse it (rollback_deploy or new deploy), and what is explicitly out of scope ('Does not change the gallery listing'). It stops short of permissions/auth requirements or propagation timing, which keeps it out of 5 territory.

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, and the headline effect is front-loaded before reversibility and scope caveats. Every sentence carries distinct 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?

No output schema and no annotations, but the description covers effect, reversibility, and non-side-effects well enough for an agent to call it confidently. Missing only edge-case behavior (e.g. unpublishing an already-offline site) and any parameter guidance.

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

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

Schema description coverage is 0% for the single required parameter, so the description should compensate and does not — projectId is never mentioned or explained. Its name is largely self-evident, so the cost is modest, but no format, scope, or sourcing guidance is added 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 ('Take a project's Codebase-hosted site offline') and even defines the observable result (address answers 404). The only gap is that it never distinguishes itself from the sibling codebase_unpublish, which an agent would reasonably confuse it with.

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 context is implied rather than stated: the reversibility sentence ('codebase_rollback_deploy or a new deploy brings it back') tells the agent this is a safe temporary action, but there is no explicit when-to-use or when-not-to-use guidance, and no guidance on choosing this over codebase_unpublish.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose what is surfaced (identity plus granted scopes), but says nothing about whether credentials are required, whether it can fail or return empty, or how scopes are formatted. For a zero-risk read tool this is adequate but thin.

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

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

A single twelve-word sentence with zero waste, front-loaded on the verb and the resource inspected. Nothing to trim and nothing 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?

With no output schema, the description usefully names the two return concepts (identity, granted scopes), which is the main thing an agent needs. It stops short of describing failure modes or scope encoding, but for a parameterless read tool the coverage is solid.

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 no parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description correctly adds no parameter noise.

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 ('Inspect') and a specific resource ('current authenticated Codebase identity and granted scopes'), so an agent knows exactly what comes back. No sibling tool touches identity or scopes, so explicit differentiation isn't needed, though it isn't called out either.

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

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

The phrase 'current authenticated' implicitly signals the use case (verifying which identity and scopes are active, e.g. before a deploy or publish), but there is no explicit when-to-use, prerequisite, or named alternative. Usage is implied rather than stated.

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