Plinth

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 it does well: it discloses the human-approval step (an email link), the asynchronous nature (poll), and the token-collection outcome. It doesn't cover failure modes, expiry of the signup request, or rate limits, but it is unusually rich for a create 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?

Two tight sentences, zero waste, with the primary action front-loaded and the required follow-up second. 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 3-param create tool with no output schema and no annotations, the description supplies the lifecycle the agent needs: email approval, signup_id, polling, token. It could say more about what the initial call returns or approval timeouts, but it is largely sufficient.

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

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

Schema description coverage is 100% (agent, email, project all documented inline), so the baseline is 3. The description adds identity semantics for email ('join theirs if their email already has one') but says nothing about the agent or project params 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+resource ('Create a Plinth account') and immediately clarifies the dual behavior: create new, or join an existing account if the email already has one. An agent can distinguish this from account.status and other siblings without opening a 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 covers the branch conditions (new vs. existing email) and prescribes the follow-up workflow: 'call account.status with the returned signup_id and poll to collect your token.' It names the sibling and the exact next action, 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 are provided, so the description carries the full burden. It discloses that the token is returned 'once', which is useful behavioral context about non-idempotency, but omits whether this is a polling operation, what happens on non-approval, or timing/rate-limit considerations.

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?

Single sentence with zero waste, front-loading the goal ('Finish signup') before the mechanics. Efficient, though not as richly structured as a top-tier multi-sentence 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?

Given no annotations and no output schema, the description should ideally cover what happens when approval is pending/rejected and the meaning of polling. It covers the happy path and the 'once' token trait, but leaves behavioral gaps for an agent to wonder about.

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 their origins ('From account.create'). The description adds no parameter-level detail beyond what the schema provides, 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 outcome: checking owner approval and returning a token upon approval. The 'Finish signup' framing distinguishes it from account.create, though it doesn't explicitly reference the sibling by name.

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?

Implied usage is that this is called after account.create to complete signup, and the schema descriptions reinforce this by saying both params come from account.create. However, there's no explicit when-to-use or when-not-to-use guidance, and the required 'poll' parameter's role is not explained.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, but it only describes return fields. It does not state that the operation is read-only, mention permissions, pagination, or any side effects, leaving key behavioral traits unaddressed.

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

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

The description is a single concise sentence with no wasted words, but it is a noun phrase fragment rather than a complete thought, reducing front-loaded clarity. It is appropriately sized for a zero-parameter tool but could be better structured.

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

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

Given the empty input schema and no output schema or annotations, the description does provide the key return fields (agents, last used, which one you are), which is adequate for a simple list tool. However, it omits whether the result is a list, ordering, or any scope limitations, leaving some contextual 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. The description does not need to explain parameter semantics, and there is no schema content to compensate for.

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 conveys the resource (agents with keys to the account) and the data returned (last used, which one you are), but never states an action verb like 'list' or 'returns'. It is not a tautology, yet it is vague about what the tool actually does and does not clearly distinguish itself from siblings like whoami or agents.revoke.

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 explicit guidance on when to use this tool versus alternatives such as whoami or agents.revoke. The description is purely declarative about output content and provides no context, prerequisites, or exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose two valuable traits: the caller must be the owner, and the effect is immediate. It omits reversibility (can access be re-granted?), error behavior, and whether the agent itself is deleted or only its account access. Adequate but incomplete 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?

Two short sentences, zero filler, and the owner-only constraint plus immediate effect are front-loaded. 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 simple one-parameter destructive operation, the description covers auth, scope, and timing. It still leaves gaps on irreversibility, re-grant behavior, and the meaning of the id, none of which are covered by annotations or an output 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 coverage is 0% and the single required 'id' parameter is never mentioned in the description. 'An agent's access' weakly implies the id identifies the agent, but no format or resolution guidance is given, so the description does not 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 (remove access) and resource (an agent), with the scope 'to this account' qualifying what is being revoked. It is clearly distinguishable from agents.list, the only real sibling, though it doesn't name it. Clear but no explicit sibling 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?

'Owner only' signals a precondition for invoking, which is useful routing context. However, it never states when to revoke versus alternatives (e.g. disabling, rotating tokens) or what happens if the caller is not the owner. 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?

With no annotations, the description carries the full burden and does add real behavioral context: no cookies, visitors counted per day (a deduplication/counting semantic), and tier-based lookback limits (today on Free, 90 days on Pro). It still omits auth/permission requirements and rate or freshness behavior, so it is strong but not complete.

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 dense sentences, front-loaded with the returned metrics and followed by counting semantics and tier limits. Every sentence earns its place with no filler or repetition.

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, but the description compensates by naming the return dimensions (per-day visitors/page views, top pages, referrers, device split). For a low-complexity read-only tool with 3 well-documented params, this is nearly complete, with only auth/permission context 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%, so the schema already documents env, days, and project, establishing a baseline of 3. The description adds only marginal meaning, contextualizing the days parameter via the Free/Pro lookback window ('per day', 'up to 90 days') without adding format or syntax 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 enumerates exactly what is returned (visitors and page views per day, top pages, referrer sources, phone vs desktop), which lets an agent distinguish this from metrics.get, logs.query, and requests.query. It is a clear retrieval of web analytics, though it never states the verb explicitly and relies on the name for the 'get' framing.

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 tier constraints ('Free shows today; Pro up to 90 days') imply the scope available to the caller, but there is no explicit when-to-use guidance and no mention of which sibling to prefer for adjacent needs (e.g., metrics.get or requests.query). 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.

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the outcome 'The owner can no longer approve it', which tells the agent this is a state-changing, effectively irreversible action. It does not say what happens if the request was already approved/denied, whether the withdrawal can be undone, or what the call returns on failure.

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 action front-loaded and the consequence second. No filler, no restatement of the name, nothing that could be cut.

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-parameter, no-output-schema tool this covers purpose, eligibility scope and end state. The remaining gap is failure/edge behavior (non-existent or already-resolved requests), which is minor given the tool's simplicity.

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

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

Schema coverage is 0% and the single parameter is documented only as a bare string 'id'. The description partially compensates by implying the id identifies a pending request the caller owns, which narrows what value to supply, but gives no format or sourcing guidance.

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 ('Withdraw a pending approval request') and constrains it to requests 'you made', which separates it from the read-only siblings approvals.list and approval.status. It stops short of naming an alternative tool, so it is clear but not fully sibling-differentiating.

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 'for example one that is no longer needed' gives an implied when-to-use condition, and 'pending' plus 'you made' scopes which requests are eligible. There is no explicit guidance on when NOT to use it (e.g. for already-decided requests) and no named alternative such as approval.status for checking first.

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 to lean on, the description still discloses meaningful behavior: newest-first ordering, the default-all status scope, that approve_url appears only on pending entries, and the out-of-band email side effect. Gaps remain on pagination, result volume, and auth requirements, but the conditional field behavior is genuinely useful 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?

Two tight sentences with the resource and ordering front-loaded and no padding. The parenthetical about email delivery is slightly extraneous but still informative, so it does not rise to 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 single-parameter, read-only list with no output schema and no annotations, the description covers what an agent needs: the scope, ordering, status vocabulary, and the notable approve_url field. Missing pagination/limit behavior is the main residual gap for a list endpoint.

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 single status enum is fully documented in the schema, including the same default note. The description restates those values rather than adding new 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 the resource (approvals requested by this account) and the ordering (newest first), which tells the agent what the call returns. It does not explicitly distinguish itself from approval.status or approval.cancel by name, but the 'list all approvals' framing makes the difference inferable.

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 default status ('all') and the note that pending entries carry approve_url hint at the browse-then-act flow. It never says when to prefer this over approval.status, nor whether it is paginated, so the agent must guess at the appropriate call for a single request.

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 one genuinely non-obvious trait - that the result contains the action output only when the approval is approved - but says nothing about pending/rejected states, permissions, or rate limits.

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

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

Two short sentences, zero filler, with the operating verb front-loaded and the return-value caveat following. Every sentence earns its place.

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

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

With no output schema and no annotations, the description is the sole carrier of return semantics, yet it describes only the approved case. An agent cannot tell what a pending or rejected response looks like, leaving a meaningful gap for a status-check 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 0% and the description never explains the single required 'id' parameter. Context implies it is the approval identifier, but format, source, or lookup requirements are left entirely unstated.

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 (check) and resource (approval), which cleanly distinguishes it from approval.cancel and approvals.list. However it does not name or contrast with those siblings, so it is clear but not fully differentiated.

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 explicit when-to-use guidance, no mention of polling versus one-shot lookups, and no routing to alternatives like approvals.list or approval.cancel. The only hint ('when approved, result holds the action output') implies a status-polling use case but never states 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 present, the description carries the full burden and does so well: it discloses the two return shapes (approve_url vs pending_approval), the out-of-band owner email/approval side effect, and the privacy guarantee that Plinth never sees card numbers. That is substantive behavioral context an agent could not infer from the empty 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-loaded with the action, then the success path, then the async path. Every clause earns its place — no restating the name, no filler — and the escalation to 'poll approval.status' lands last where the agent needs it.

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, so the description must explain returns; it covers both response cases and the required next step for each. For a 0-param, annotation-less tool this is complete enough to call correctly without opening anything else.

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 are zero parameters, so the baseline is 4. The description instead spends its words on return semantics (approve_url, pending_approval) and the approval flow, which is the right place for value given a 0-param tool.

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 and resource: ask the owner to add or replace the payment card. The name 'billing.card' alone is ambiguous (could read as a read op), but the description immediately disambiguates it as an owner-approved write flow. It does not explicitly name siblings like billing.status or approval.status as points of contrast, 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?

Gives clear operational context: approving opens a Stripe page, and if pending_approval is returned the agent should tell the owner it is waiting and then poll approval.status. This is actionable post-invocation guidance with a named follow-up tool, though it doesn't state exclusions or when to prefer an alternative (e.g. billing.status) before calling.

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 supplied, so the description carries the full behavioral burden. It usefully discloses the contents returned (card-on-file flag, current spend, cap, recent charges), which partially compensates for the absent output schema, but it never states that this is a read-only operation or whether any permissions are required.

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 compact sentence with no filler, and the most important fact (card on file) leads. It is a fragment rather than a sentence, but 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?

For a zero-parameter read tool with no output schema, enumerating the returned fields gets close to complete. However, the missing read-only confirmation and the absence of any routing versus billing.card leave gaps an agent would notice.

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. The description correctly adds no parameter information and the empty schema leaves nothing 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?

The description enumerates what the tool reports (card on file, spend, cap, charges), which tells an agent the resource, but it is a noun phrase with no verb and never frames the operation as a status read. It also fails to differentiate from the sibling billing.card, which plausibly overlaps in subject matter.

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 condition selecting this tool over billing.card or account.status, and no prerequisites. The agent must infer the trigger from the 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?

No annotations are provided, so the description carries the full burden, and it does add real behavioral value by disclosing the return fields (path and size) and the ref scoping. However it says nothing about permissions, pagination, or result limits for large repositories, which is a notable gap for a no-annotation 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?

A single sentence with no filler, front-loaded with the verb and resource, and the return fields and scope are packed in without 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?

With no annotations and no output schema, the description does convey what comes back (path and size), which helps. But details an agent would want before calling it — large-repo behavior, whether the listing is recursive, permission requirements — are absent.

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 ref, prefix, and project are all documented in the schema, making 3 the baseline. The description adds only a slight restatement of the ref semantics ('branch or commit') and never mentions prefix, so it does not exceed 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 (list), resource (files in the project repo), and even the return shape (path and size), scoped to a branch or commit. It is distinguishable from code.read and code.write by implying directory listing rather than content access, though it never names those siblings.

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 scope ('on a branch or commit', folder filtering) but there is no explicit when-to-use, no exclusions, and no routing to siblings such as code.read for file contents or git.branches for branch enumeration.

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 usefully discloses that text is returned as utf8 and binary files as base64, but it omits auth requirements, error behavior for missing files, and explicit confirmation that the operation is non-mutating.

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

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

The description is two short, front-loaded sentences with no wasted words. The core purpose is stated first, followed by the important return-encoding detail.

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

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

For a simple read operation with no output schema, the description explains the return encoding and file scope. The main remaining gap is the undocumented path parameter and absence of error/auth context, but these are minor for this 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 67%, with project and ref documented in the schema and path undocumented. The description adds context that the file belongs to a project repo, but it does not add path syntax or clarify the project/ref/path roles 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 specific verb and resource: 'Read one file from the project repo.' It also clarifies scope ('one file') and distinguishes the operation from siblings like code.list and code.write.

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 'Read one file from the project repo' implies when the tool is appropriate, but it does not explicitly state when to use it instead of code.list or code.write. No exclusions or alternative-routing guidance are provided.

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 substantial work: it discloses that the tool writes AND deletes, that main deploys to staging while other branches get previews, that a deploy is triggered, and that whole files up to 5 MB are expected. It omits auth requirements, atomicity/reversibility of the commit, and error behavior, which are meaningful 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?

Four tight sentences, front-loaded with purpose before constraints. Each sentence adds distinct information (audience, branch behavior, payload format, size cap) with no repetition of the schema.

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 and no output schema, the description covers purpose, branch/deploy effects, payload format, and size limits well. It stops short of describing what the call returns (commit id, deploy id, status) and any auth requirements, which an agent would need given the absence of an output 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 coverage is 80%, so the baseline is a 3, and the description adds real value: 'whole files' semantics, text-as-utf8 vs binary-as-base64, and a '5 MB per file' limit that is not present in the schema. It also clarifies the branch parameter's deployment consequence (staging vs preview), which the schema's 'Default main' does not.

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 precise verb and resource ('Commit files to the project without git') and immediately scopes it as a git replacement for agents without CLI access. This cleanly separates it from siblings like git.revert/git.remote and from the read-oriented code.list/code.read.

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 clause 'for agents that cannot run git or the CLI (e.g. Claude or ChatGPT in the cloud)' gives a clear when-to-use condition and implicitly a when-not (agents that can run git). It does not explicitly name git.* or the deploy sibling as alternatives, so routing is implied rather than spelled out.

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 so well: it discloses the out-of-band email flow, the 12-hour session lifetime, the critical constraint that the agent never receives a session, and the possible pending_approval outcome. These are exactly the behavioral facts an agent needs before calling.

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 tight sentences, front-loaded with the purpose and mechanism, then the deferred-approval path. Every sentence carries information; none is 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 and no annotations, so the description must cover returns — it covers the pending_approval branch and the follow-up tool, but does not describe the shape of a successful (non-pending) return. Minor gap for an otherwise complete flow description.

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 per the rubric the baseline is 4. There is no parameter surface for the description to clarify or compensate for.

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 ('Get the owner into the web console') and immediately explains the mechanism (Plinth emails a sign-in link, approving signs that browser in for 12 hours). It is clearly distinct from siblings like approval.status or account.create.

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

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

Tells the agent exactly when this applies and what to do on the deferred path: if pending_approval is returned, tell the owner it is waiting, then poll approval.status. This routes the agent to the correct sibling tool under an explicit condition.

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 behavioral weight and delivers a lot: the POST-per-tick mechanism, the 5-field UTC cron semantics, the x-plinth-cron-secret auth header, the /api/cron/ caller restriction, and the paused-by-default behavior outside production unless enabled is true. Gaps remain around required permissions and error behavior on an invalid schedule, but this is well above average 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?

Three dense sentences with the core action front-loaded and zero filler. Every clause (auth header, path restriction, paused default, declarative alternative) 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 6-param creation tool with no annotations and no output schema, the description covers the critical runtime behavior an agent needs. It stops short of permission requirements and failure modes, but nothing essential for a correct invocation 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 coverage is 67%, and the description adds genuine meaning beyond it: it explains the schedule format (5-field, UTC), the security implication of the path, and—most valuably—the semantics of the undocumented 'enabled' param (default paused outside production). The 'name' and 'project' params get no added context.

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 ('Schedule a job') and immediately clarifies the mechanism (Plinth POSTs to path on each tick). The purpose is unambiguous against the cron.* sibling set, though it never explicitly distinguishes itself from cron.run, cron.resume, etc.

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

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

Implied usage is clear (create a scheduled job), and it mentions the declarative alternative in plinth.json 'crons'. However, it gives no explicit when-to-use guidance relative to siblings like cron.run or cron.resume, and no prerequisites for choosing the API over the declarative route.

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

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

No annotations are provided, so the description carries full behavioral burden. It mentions the listed cron jobs include last run and next run metadata, but does not state that this is a safe read-only operation, whether permissions are required, or whether results are paginated or filtered by anything beyond project and environment.

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 single sentence is appropriately short and front-loaded, with no filler. It is efficient, though it sacrifices some clarity by not using an explicit verb.

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 low-complexity list operation with fully documented parameters and no output schema, the description gives the essential resource and returned metadata. However, with no annotations and no output schema, it could still clarify read-only behavior and scope more explicitly.

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 both required parameters (project and env) already documented in the input schema. The description adds no additional parameter meaning, so the baseline score 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?

The description names the resource (cron jobs) and scope (on an environment) and hints at returned fields (last run and next run), but omits an explicit action verb such as 'List'. It is inferable from the tool name and siblings, but not clearly distinguished from cron.runs, which likely lists individual job runs.

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 explicit when-to-use guidance, no alternatives mentioned, and no exclusion criteria. The only implied usage is that it retrieves cron jobs for a given environment, leaving the agent to infer context from the name and 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?

With no annotations, the description carries the full burden, and it does disclose the key behavioral fact that the job is not deleted and simply stops running, which signals reversibility. It omits whether in-flight executions are killed, whether the call is idempotent, and what permissions or response to expect.

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, with the clarifying clause placed where it is needed. Nothing is wasted and nothing important 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?

For a flat three-parameter mutation with no output schema and no annotations, the description supplies the one thing an agent cannot infer from the name: that pausing preserves the job definition. Remaining gaps (in-flight runs, return shape) are minor for a tool this simple.

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?

Three required params at 67% schema coverage: env and project are documented in the schema, name is not, and the description adds no parameter meaning at all. The parameters are largely self-describing so the gap is tolerable, but the description contributes nothing 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 (pause) and resource (cron job), and the parenthetical pins down what 'pause' means in this system: the job stays defined but does not run. That distinguishes it in spirit from cron.remove and cron.run, though no sibling is named 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 only implied: by saying the job 'stays defined', the agent can infer this is the reversible alternative to cron.remove, but the description never says when to pause versus remove, run, or resume, and gives no prerequisites.

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

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

With no annotations provided, the description carries the full burden, and it states only 'Delete a cron job.' It does not disclose whether deletion is permanent or reversible, what permissions are required, or what happens to run history. It does convey the mutating nature of the operation via the verb 'Delete', but nothing beyond that.

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 that is front-loaded with the action and resource. It is efficient, though arguably too terse given the destructive nature of the operation.

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, three-required-parameter tool with no annotations and no output schema, the description is inadequate. It omits permanence, permission requirements, and confirmation behavior, leaving key agent decision inputs unspecified.

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 67%, with 'name' undocumented in both the schema and the description. The description adds no meaning to any of the three parameters (project, env, name), leaving the agent to infer from schema alone.

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 ('Delete') and resource ('cron job'), which distinguishes it from sibling tools like cron.add, cron.pause, and cron.resume. However, it does not explicitly differentiate itself or note scope (e.g., whether deletion is permanent vs. disabling).

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 alternatives such as cron.pause or cron.resume, which are likely the safer options for stopping a job temporarily. No prerequisites or conditions are 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. It conveys a state-changing mutation but omits permissions required, idempotency, side effects, and what happens if the job is not paused. Disclosure is minimal.

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 and the action is immediately clear.

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 mutation tool with no output schema, the description states the action adequately. However, with no annotations it should ideally cover prerequisites and behavioral details; the current text is minimum viable but leaves gaps.

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

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

Schema coverage is 67%: env and project have descriptions, but name does not. The description adds no parameter meaning, leaving the 'name' parameter (likely cron job name) and the interaction of project/env unexplained 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 ('Resume') and resource ('cron job'), qualified by 'paused'. It clearly implies the inverse of cron.pause, but does not explicitly name or distinguish itself from siblings like cron.pause or cron.run.

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 'paused' implies the precondition that the job must be paused, so usage is implied. However, there is no explicit when-to-use, when-not, or alternative guidance (e.g., vs cron.run), leaving the agent to infer conditions.

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

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

No annotations are provided, so the description carries full behavioral burden. 'Return its result' hints at a synchronous response, but nothing is said about permissions required, whether the job runs with the same env/prod credentials, whether a failed job blocks the call, or how long it may block. For an execution-triggering tool with zero annotation coverage this is a significant gap.

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

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

A single compact sentence that front-loads the action and states the return behavior. No filler, nothing to trim.

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/execution tool with no annotations and no output schema, the description is far too thin. An agent cannot know the authorization model, whether the run is synchronous or fire-and-forget, or what 'result' contains. The name parameter is also undocumented anywhere.

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 67%: env and project are documented, but 'name' has no description in either schema or description. The description adds no parameter-level detail. With only two-thirds coverage and no description compensation, this is at the baseline rather than above it.

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: 'Run a cron job now' is clear and distinguishes it from siblings like cron.add, cron.list, cron.pause. It could be even sharper by mentioning it targets an existing job in a specific project/env, 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?

The word 'now' implies manual/on-demand execution vs the scheduled runs that presumably happen automatically, and the sibling cron.runs exists for listing past runs. But no explicit when/when-not or alternative guidance is given; the agent must infer that this is for manual triggering rather than viewing history.

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 implies a read operation by saying 'Recent runs,' but says nothing about permissions, pagination, retention limits, or what a run record contains. For a history-retrieval tool with zero annotation coverage, this is a significant gap.

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

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

The description is a single front-loaded phrase with no filler or redundancy. It is efficient, though its brevity contributes to the overall under-specification of the tool.

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

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

The tool has three required parameters and no output schema, so the description should explain the return shape and scope. It only says 'Recent runs' without defining how many runs, whether they are filtered by project/env, or what fields each run includes. This is insufficient for a history-list operation.

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

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

Schema coverage is 67%: env and project have descriptions, but name does not. The description adds no parameter-level meaning; it does not say that name identifies the cron job or that project/env scope the job. It fails to compensate for the undocumented name parameter.

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

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

The description identifies the resource and scope ('Recent runs of a cron job'), so an agent can infer it returns run history. However, it lacks an explicit verb and does not distinguish itself from the singular sibling cron.run or explain how it differs from cron.list. This is adequate but vague.

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 cron.run, cron.list, or other cron-related siblings. The description does not mention prerequisites, when-not-to-use, or alternative tools for inspecting run history.

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 disclose a non-obvious async flow: it may return pending_approval, the owner is emailed a link, and the caller must poll approval.status. It does not state that the return value is a sensitive credential to handle carefully, nor what auth is needed for non-production environments.

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 purpose and packs the approval caveat and follow-up into a compact, semicolon-joined structure with no filler. Dense but readable, with nothing that wastes space.

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 2-param tool with no output schema, the description covers the key non-obvious behavior including the pending_approval return shape and the polling loop. Missing only auth/permission details for non-production envs and secret-handling guidance, which are minor gaps here.

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 params (project, env) are already documented in the schema. The description references 'production' and 'environment' conceptually but adds no new parameter-level meaning beyond the schema baseline.

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

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

States a specific verb+resource ('Get the DATABASE_URL for an environment') and adds the scope qualifier that it is the same value the app receives. It does not explicitly differentiate from siblings like env.secrets.list or db.query, which also touch environment data, but the purpose 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 context for the approval path (production requires owner approval) and the follow-up action (poll approval.status). It stops short of naming when to prefer this over alternatives such as env.secrets.list, so it falls just below full when/when-not 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?

With no annotations, the description carries the full burden and does so well: it discloses the snapshot-before-apply safety behavior and, unusually, an asynchronous approval gate ('May return pending_approval', owner emailed, expected follow-up polling). This is behavior an agent could not infer from the schema.

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

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

Three short sentences, front-loaded with the action and its relationship to deploys, then the side effect, then the edge-case return path. 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, yet the description covers the notable return case (pending_approval), the side effect (snapshot), and the required follow-up, so an agent knows both what it does and what to do with the result.

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% for both required parameters (project, env), so the schema already documents them. The description adds no format or constraint detail beyond the schema, 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 ('Apply pending migrations'), scopes it to the live release, and immediately contextualizes it against the deploy flow. An agent can distinguish it from db.migrations (listing) and deploy without opening either 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?

The parenthetical 'deploys do this automatically' signals when manual invocation is warranted, and the description routes the agent to approval.status for the approval branch. It stops short of an explicit when-not statement or naming db.migrations as the alternative for inspection.

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 behavioral burden, and it does disclose useful mechanics: migrations live in migrations/*.sql and are applied in name order. However, it never states that this is a read-only operation, whether it requires elevated permissions, or how output is structured, leaving the safety profile unstated.

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 compact sentence with the resource and its scope front-loaded and zero filler. Every clause (applied/pending, file source, ordering) adds 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?

For a simple two-parameter read tool, the description covers what the tool returns (applied and pending migrations) even though there is no output schema. It is nearly complete, with only the read-only nature and the db.migrate distinction left implicit.

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 (project, env) are already documented in the schema, and the description adds no further parameter detail. This matches the 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?

The description clearly identifies the resource (migrations) and its content (applied and pending), plus the underlying source (migrations/*.sql). It reads as a status/listing tool, but uses a noun phrase with no explicit verb and never names the sibling db.migrate that it is easily confused 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?

There is no when-to-use guidance and no mention of the alternative db.migrate, which performs the migration rather than reporting on it. The closest sibling is left unaddressed, forcing the agent to infer the distinction from the 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?

With no annotations, the description carries the burden and does well: it discloses the 500-row cap, that production reads run in a read-only transaction, that writes require owner approval, and the pending_approval/email/polling flow. Missing timeouts, rate limits, and error semantics, but this is far above baseline for a mutation-capable 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?

Four tight sentences, front-loaded with the core action, then row cap, then the production policy, then the approval flow. 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, so the description must cover returns; it names the row limit and the pending_approval case, which is the highest-risk outcome. It stops short of describing the normal result shape or error responses, so it is good but not fully self-contained.

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

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

Schema coverage is 50%, and the description meaningfully clarifies the env parameter by tying 'production' to read-only transactions and approval-gated writes. However it says nothing about the undocumented params array (bind parameters) or the project scoping, leaving half the parameters to inference.

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 ("Run SQL against an environment database") and scopes the target (environment database). It doesn't explicitly contrast with siblings like db.migrate or db.snapshot, but the operation 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?

Explains the production read/write split and names the follow-up tool (approval.status) with the condition that selects it. It lacks guidance on when to prefer this over db.connection or env.exec, but the production gating is genuinely actionable.

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 a side effect ('takes a safety snapshot first'), an authorization requirement for production, and a non-obvious return branch with its downstream action. It omits that a restore overwrites/replaces current data (destructiveness) and any downtime expectation, leaving a gap for a mutation this risky.

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?

Four short sentences, front-loaded with the action, followed by side effect, permission gate, and return-handling. No filler; every sentence carries operational 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?

For a 3-param mutation with no output schema and no annotations, it covers the crucial non-obvious behaviors (safety snapshot, approval gating, pending_approval handling). It stops short of covering the success-path result and any downtime/reversibility caveats an agent might want to relay.

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 67%: env and project are documented in the schema but 'snapshot' has no description. The description references snapshots only generically and doesn't explain the identifier format or point to db.snapshots for retrieving one, so it adds little beyond the schema for the uncovered parameter.

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

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

States a specific verb and resource ('Restore an environment database from a snapshot'), which cleanly distinguishes it from the snapshot-creating siblings db.snapshot/db.snapshots. An agent knows exactly what action this performs without inspecting 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?

Gives clear contextual guidance: production requires owner approval, and it explains the pending_approval branch with the follow-up step (tell the owner, then poll approval.status). It doesn't name alternative restore/rollback tools, but the conditional flow is explicit enough to invoke correctly.

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 disclosure burden, and it discloses very little: it does not say whether the dump is synchronous or asynchronous, how long it takes, where the artifact is stored, whether it requires credentials/access to production, or what it costs in resources. Only the underlying utility (pg_dump) is revealed.

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 zero waste; the verb and resource lead and the parenthetical mechanism is useful. It is arguably too terse for a state-changing tool, but as raw structure it is clean.

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 one undocumented parameter, the description should at minimum say where the snapshot goes, how to enumerate it later (db.snapshots), or how it is consumed (db.restore). None of that relational context is present.

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 67%: 'env' and 'project' are documented in the schema, while 'label' has no description anywhere. The tool description adds nothing about any parameter, so the undocumented 'label' is left entirely unexplained.

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 ('take a snapshot') plus the resource ('environment database') and even the mechanism ('pg_dump'), which is more than a tautology. It does not, however, differentiate itself from the close sibling db.snapshots, so an agent must infer the distinction on its own.

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 prerequisites, and no mention of alternatives such as db.snapshots (list) or db.restore (restore). The agent is left to infer that this is the creation path and those are the read/restore paths.

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. 'List' implies a safe read, and it usefully discloses that staging/production snapshots are automatic at 03:00 UTC and retained 7 days. However, it omits auth/permission requirements, pagination behavior, and whether preview environments also have snapshots.

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 lifecycle context placed second. No filler or repetition.

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

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

The description covers purpose and snapshot retention, which is helpful for a simple list tool. But with no output schema and no annotations, it should say more about the return shape (e.g., fields, ordering) and any pagination or permission constraints to be fully 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 100%, so both parameters are already documented. The description adds no syntax, format, or filtering detail beyond what the schema provides, making the baseline score of 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 ('List') and resource ('snapshots') scoped to an environment. It does not explicitly distinguish itself from the singular sibling 'db.snapshot', which likely creates a snapshot, so an agent must infer the difference from the plural noun.

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 no when-to-use guidance, no prerequisites, and no routing to alternatives such as db.snapshot (create) or db.restore. The note about automatic nightly snapshots is contextual background, not usage direction.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the branch-tracking scope and a production guardrail (routing users to promote), but says nothing about permissions, whether the deploy is synchronous or queued, what happens to a failed rebuild, or how to undo (rollback exists as a sibling).

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, zero filler, with the core action front-loaded and the constraint trailing as justification. 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 3-parameter tool with full schema coverage and no output schema, the description covers the action, the tracked-branch semantics, and the key production exclusion. It stops short of describing execution behavior (async/blocking, failure handling) that an agent would want before calling a deploy.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some value by explaining the env-to-branch mapping ("staging tracks main") and reaffirming the branch-head default for commit, but it never addresses the commit parameter or the production restriction on env beyond pointing at promote.

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 compound verb (rebuild and deploy) and a precise resource: the head of the branch an environment tracks. It also implicitly separates itself from sibling tools like promote (which owns production changes) and deploy.cancel/deploy.status, so an agent can route correctly without reading other schemas.

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 when-not condition and the alternative: "Production only changes via promote." Combined with the parenthetical explaining that staging tracks main, an agent knows exactly when this tool applies versus the promote sibling.

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 that 'the live release keeps serving,' which is real behavioral context for a cancellation tool. However, it omits what happens to the stopped build (is it discarded? re-runnable?), permission requirements, and the release id 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 tight sentences with zero filler. The primary action is front-loaded, and the scope qualifier and the live-release reassurance follow 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 destructive-ish cancellation tool with no annotations, no output schema, and one schema-undocumented parameter, the description covers the core semantics but stops short of return behavior, error conditions, and the fate of the cancelled build.

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 67%; env and project are already described in the schema. The description adds meaning to the undocumented 'release' parameter by clarifying it refers to a release id and is alternative to targeting the latest build. It still gives no format or example for that id.

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 ('Stop') and resource ('a build that is still running'), scoped precisely as the latest in the environment or a given release id. It is clearly distinguishable from siblings like rollback, promote, and deploy.status, which do not cancel running builds.

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 scopes which build is targeted and implicitly signals the condition ('still running'), but it never names alternatives or exclusions — e.g., no guidance on when to prefer rollback or deploy.status instead. Usage is therefore 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?

With no annotations, the description carries the full burden and does disclose non-obvious behavior: result ordering (newest first), that the build log is only for the latest release, and the incremental-log continuation mechanism via log_from offset and build_log_length. It stops short of stating auth/permission needs or explicitly confirming it is read-only.

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

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

Two tight sentences, front-loaded with the core purpose and return shape, then the pagination detail. Every clause earns its place and nothing is padded.

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/status tool with no annotations and no output schema, the description adequately conveys what comes back (releases, status, latest build log) and how to page through logs. The main remaining gap is the undocumented limit parameter, which an agent cannot interpret from any source.

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 50%: env and project are documented in the schema, while limit and log_from are not. The description compensates well for log_from ('a character offset', continuation via build_log_length) but leaves limit entirely unexplained in both schema and description, so it only partially fills 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 resource (releases for an environment) with ordering (newest first) and content (status plus build log of the latest), which clearly distinguishes it from action siblings like deploy, deploy.cancel, and rollback. It does not, however, explicitly name a sibling it is the read counterpart to, 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 by the read-only 'status' framing; there is no explicit when-to-use or when-not-to-use statement, and no alternatives (e.g. deploy, logs.query) are named. The log_from continuation note is closer to parameter guidance than selection 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?

With no annotations, the description carries the full burden and does much of it: it discloses the three side effects, that price is shown to the owner before purchase, that only standard registrations are handled, and the asynchronous pending_approval path with its follow-up. It stops short of permissions, reversibility/refund behavior, or timing expectations for registration.

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 core action and its side effects, then the constraints and the async path in descending order of importance. No filler sentences; every clause carries operational meaning.

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 paid, side-effecting tool with no output schema and no annotations, the description covers the critical return case (pending_approval) and the required agent behavior. It leaves cost visibility, failure/refund handling, and registration timing unaddressed, which keeps it just below fully 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 100%, so env/project/domain/years are already documented, including the '1-10, default 1' constraint and the domains.search prerequisite. The description adds only the abstract constraint 'standard registrations only', which is a marginal gain over the schema baseline.

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

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

States a specific verb and resource (buy a domain) and expands the scope with the concrete effects — registers it, points DNS at Plinth, issues HTTPS. Combined with the schema hint to run domains.search first, an agent can distinguish this from domains.connect/domains.verify without opening another 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?

Gives real routing conditions: 'Standard registrations only' excludes non-standard cases, and the pending_approval flow tells the agent exactly what to do (inform owner, then poll approval.status). It does not, however, contrast domains.buy against domains.connect or domains.orders, so the alternative-selection guidance is incomplete.

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 that the call returns the DNS record to create, which hints it is a configuration step rather than a completed state change. It omits whether the operation is idempotent, what happens on re-connect, permission requirements, and whether DNS ownership is validated.

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 waste; the core mapping action is front-loaded, followed by the practical next step. Nothing superfluous is included.

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 partially compensates by noting the returned DNS record to create. For a mutation tool with three required params and no annotations, though, missing prerequisites, idempotency, and failure behavior leave real 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%, so env/host/project are already documented in the schema, and the description adds no field-level syntax or format guidance. Baseline 3 is appropriate when the schema does the work and the description only echoes the concepts.

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: "Map a domain you own to an environment." The phrase "a domain you own" implicitly separates it from domains.buy/domains.search, though no sibling is named outright. An agent can tell what it does 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?

It gives the post-call instruction ("Point its DNS at the Plinth host"), which implies the usage flow after invocation. However, it never states when to use this versus domains.verify or domains.list, nor the prerequisite that the domain likely must already be purchased/verified before connecting.

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 state that this is a read-only operation, whether authentication or project permissions are needed, or what the result contains. 'Mapped to a project' is the only behavioral hint, leaving the safety profile undocumented.

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

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

The description is a single short fragment with no wasted words, but it lacks a leading verb and reads as under-specification rather than deliberate brevity.

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

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

For a tool with no annotations and no output schema, the description should at least confirm it is a listing operation and hint at what is returned (e.g. domain names, verification state). Neither is present, so an agent lacks enough to 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 100% (only 'project' is documented as 'Project name'), so the baseline is 3. The phrase 'mapped to a project' reinforces the scoping role of the parameter but adds no format or lookup 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 names the resource (domains) and its scope (mapped to a project), which implies a project-scoped listing, but it is a noun fragment with no verb and no differentiation from siblings like domains.orders, domains.search or domains.verify. An agent can roughly infer a read/list operation, but nothing confirms it or separates it from the other domain 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the seven sibling domains.* tools. The only implicit context is that a project is required.

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 does not state that the call is read-only, has no side effects, requires account authentication, is paginated, or what the response shape is; it merely names three fields, which is insufficient behavioral context for a zero-annotation 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 front-loaded sentence with no filler. It efficiently communicates scope ('on this account') and returned fields in a single clause.

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 explain the return data; it names price, status, and expiry, which is a reasonable summary for a simple zero-parameter read. It omits the collection structure (list/array), ordering, and pagination, leaving minor gaps, but the tool's low complexity keeps this close to sufficient.

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

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

There are zero parameters and 100% schema description coverage, so the baseline of 4 applies. The description adds no parameter information, which is appropriate because none exist.

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 the resource (domains bought through Plinth on this account) and the returned fields (price, status, expiry) in one phrase, so an agent can infer this is a read tool for order records. However, it never uses an explicit verb like 'list' or 'get' and does not mention or contrast with the sibling domains.list, so sibling differentiation is absent.

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

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

Provides no when-to-use guidance and never names domains.list, domains.buy, or any alternative. The only hint is the word 'bought', which distinguishes historical orders from currently managed domains, but that is inference rather than instruction.

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, yet it discloses nothing about permission requirements, whether the unmapping is reversible, whether the domain's DNS/registration is affected, or the response behavior. 'Unmap' hints at a state-changing operation, but no behavioral detail follows.

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 single sentence is front-loaded and wastes no words. The brevity is under-specification rather than efficient density, but structurally it is clean.

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-required-parameter mutation with no annotations and no output schema, the description is far too thin. An agent lacks the behavioral and parameter context needed to invoke this 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 coverage is 50%: 'project' has a description ('Project name') while 'host' is bare, and the description adds no meaning for either. It does not clarify that host is the domain to be unmapped from the given project, leaving the parameter gap unfilled.

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 pairs a verb ('Unmap') with a resource ('domain'), which distinguishes it from siblings like domains.buy, domains.connect, and domains.verify. However, 'unmap' is jargon that never states what is actually unlinked (a host from a project) or what state changes, so the purpose is only vaguely conveyed.

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 versus domains.connect, domains.verify, or project.delete, and no prerequisites or exclusions are given. The agent must infer usage entirely 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 behavioral burden and does disclose a key trait: passing a bare name expands to eight TLDs (.com, .dev, .app, .io, .co, .net, .ai, .org) rather than a single lookup, and it returns price. It does not mention rate limits, auth requirements, or whether pricing is per-TLD.

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, front-loaded with the purpose and followed by the input semantics. The parenthetical TLD list is information-dense and earns its place; 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 and no annotations, so the description must stand alone, and it covers both input interpretation and the headline return value (price/availability). It is nearly complete for a simple lookup, though it omits result shape details like whether all TLDs are always returned.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema's terse 'e.g. acme or acme.dev' by explaining exactly what a short name does (expansion across TLDs) versus submitting a full domain. This materially changes how an agent would call it.

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 ('Check if domains can be bought here, with price'), making the availability-check role clear against siblings like domains.buy, domains.list, and domains.verify. It does not explicitly name or contrast those siblings, so it falls short of 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 'can be bought here' framing implies this is a pre-purchase availability lookup, but the description never states when to use it versus alternatives such as domains.buy or domains.list, nor any exclusions. Usage is only inferable from context.

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

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

With no annotations, the description carries the full burden. It usefully discloses the success condition (TXT match leads to the domain being served), but does not say whether the call is read-only or mutates serving state, whether it is idempotent/safe to poll, or what happens on mismatch.

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 no filler. It is efficient, though arguably too terse for the amount of behavior an agent needs to know.

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 annotations and no output schema, so the description is the only guidance. It covers what happens on success but omits failure handling, whether the TXT value is returned for comparison, and retry/polling expectations — gaps that matter for a verification 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 only 50% (project is described as 'Project name', host is bare). The description partly compensates by framing 'the domain' as the target of the TXT check, implying host is the connected domain name, but adds no format or sourcing detail.

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 (check) and resource (TXT record of a connected domain) plus the resulting state transition (domain is served). This is clearly distinguishable from domains.connect/domains.buy, though the sibling differentiation is implied rather than named.

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 hints that this is part of the connect flow but never says when to call it versus domains.connect or domains.list, how often to retry on a mismatch, or what prerequisites (DNS propagation) must hold. Usage is left 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?

With no annotations provided, the description carries full behavioral burden and does so well: it discloses the production owner-approval requirement, the 30s timeout, the 20 KB output cap, the read-only code with writable /tmp, and the pending_approval flow with polling via approval.status. This is exactly the context an agent needs beyond the schema.

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

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

Front-loaded with the critical production-approval caveat, then the core action, then limits, then the approval flow. Every sentence earns its place. Slightly dense but well organized; minor room for trimming the example list.

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 no output schema and no annotations, the description provides a remarkably complete picture: execution context, limits, write constraints, and the approval/polling workflow with the correct sibling reference (approval.status). An agent can invoke this correctly without further info.

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 50%: 'env' and 'project' are documented in the schema. The description adds no explicit semantics for 'command' or 'timeout_seconds' (which are undocumented in both). It slightly clarifies 'command' via examples like 'node -e ...' and 'ls', but 'timeout_seconds' remains unexplained. Baseline 3 is appropriate given the partial coverage.

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 ('run a shell command inside the environment's running sandbox') with the exact execution context (same code, env vars, network, limits as the app). The description distinguishes this from siblings like code.read or db.query by scoping it to shell execution inside the running sandbox.

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?

Clearly implies when to use it: to inspect or execute within the live sandbox, with concrete examples ('node -e ...', 'ls', 'env | sort'). It also notes the approval condition for production and directs to approval.status. However, it doesn't explicitly rule out alternatives or say when NOT to use it (e.g., vs. code.read or logs.query).

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, yet it never states that this is a read-only operation, whether results are paginated, or how large the response can be. The only behavioral hint is that each environment carries a live release and URL, which is minimal 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?

It is a single front-loaded fragment with no wasted words, but it is under-specified rather than genuinely concise. The trailing 'with live release and URL' phrase is ambiguous about whether it describes return fields or filter criteria.

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 low-complexity, single-parameter tool with no output schema this is roughly the minimum viable amount, since the return content is sketched (live release, URL). However, it omits read-only framing and any routing against the many sibling env.* 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?

There is a single parameter with 100% schema description coverage, so the schema already documents 'project'. The description adds no format, naming, or validation detail 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?

The fragment names the resource (environments) and its scope (a project) and hints at return content (live release and URL), but it is a noun phrase rather than a specific verb+resource statement. It does not clearly distinguish itself from sibling read tools like env.status, so an agent must infer that this lists rather than reports status.

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 prerequisites, and no mention of alternatives such as env.status or env.exec. The agent is left to infer from the name alone that this is the enumeration variant.

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 core behavioral outcome: a fresh sandbox is created while code and data are preserved. It does not mention auth requirements, downtime, or rate limits, so it is strong but not comprehensive.

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 redundant or wasted wording. Every clause—verb, resource, scope, and state outcome—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 tool with no output schema, the description covers the purpose and the key state effect. With no annotations, it could still say something about permissions or side effects, but it is largely adequate for the tool's low complexity.

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 ('project', 'env') are fully documented in the schema itself. The description adds no further parameter-level meaning. A baseline 3 is appropriate 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 ('Restart an environment') and adds scope ('on its current release') that implicitly distinguishes it from deploy, promote, or rollback by clarifying code and data are unchanged. It does not explicitly name an alternative sibling, 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?

The parenthetical '(fresh sandbox, same code and data)' gives context that implies when to use it—when a runtime reset is needed without changing code or data—but it never explicitly states when to use this over alternatives like deploy or rollback. No exclusions or named alternatives are provided.

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

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

With no annotations, the description carries the burden and does disclose non-obvious side effects: a single restart at the end and that VITE_/NEXT_PUBLIC_/PUBLIC_ keys also reach the build. It still omits permission/auth requirements and whether existing variables are overwritten by default (the replace parameter only appears in the schema).

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

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

Two densely packed sentences, correctly front-loaded with the core action before the format details and the restart/build caveats.

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 no output schema and no annotations, the description covers the important behavioral footnotes (single restart, build propagation). Only marginal gaps remain around auth and merge semantics, the latter partly covered by the schema's replace field.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to the 'dotenv' parameter by specifying that # comments, quotes, and 'export' prefixes are accepted.

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 (set many environment variables at once) and names the source format (.env text), which cleanly distinguishes it from the single-key sibling env.secrets.set.

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 'from .env text' and the bulk framing, but there is no explicit when-to-use versus env.secrets.set or env.exec, and no stated prerequisites or exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one genuinely valuable, non-derivable trait: secret values are redacted. However, it says nothing about required permissions, whether the result is ordered/paginated, or how preview environments behave.

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 sentence, front-loaded with the action and immediately qualifying the return contents. 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?

For a simple two-required-param read tool, the definition plus schema is nearly sufficient, and the redaction note compensates for the absence of an output schema by clarifying that only names come back. Missing only auth/permission expectations and result ordering.

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 (project, env) are already fully documented in the schema, including the production/staging/preview values. The description adds no parameter-level meaning 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?

Specific verb+resource: lists environment variable *names*. It implicitly separates itself from env.secrets.set/unset/import by being the read-only enumeration, though it never names those siblings explicitly. An agent can tell what it returns (names, not values) 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?

Usage is only implied: the 'values are never returned' note hints at the use case of auditing which secrets exist without exposing them. There is no explicit when-to-use statement, no when-not, and no pointer to env.secrets.set/unset as the mutating alternatives.

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

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

With no annotations, the description carries the full burden, and it does disclose one critical side effect: the env is restarted so the change takes effect. That is genuinely useful behavioral context. It omits overwrite semantics for existing keys, permissions required, and whether the restart causes downtime.

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-loading the action and then the side effect with zero filler. Efficient, though slightly terse given the operation's risk profile.

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 four-required-parameter mutation with no annotations and no output schema needs more: overwrite behavior, auth requirements, and restart impact are all unstated. The restart note is a start but leaves significant gaps for a mutating 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 only 50%: only env and project are documented in the schema, leaving key and value bare. The description adds no meaning to any of the four parameters, 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?

States a specific verb+resource: setting an environment variable, scoped to an environment. It is readily distinguishable from env.secrets.unset/import/list by the action word, though it doesn't explicitly name those siblings.

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 versus env.secrets.import (bulk) or env.secrets.unset, and no prerequisites or exclusions are given. The agent must infer the single-key vs bulk distinction from the 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?

With no annotations, the description carries the full behavioral burden and does not meet it. It implies a destructive, likely irreversible mutation but says nothing about reversibility, required permissions, behavior when the key doesn't exist, or whether the running environment is affected. Only the minimum mutation semantics are conveyed.

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 action is stated immediately. It is efficient, though the brevity borders on under-specification rather than genuine 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?

A destructive mutation with no annotations, no output schema, and an undocumented required parameter needs considerably more context than one sentence. Missing guidance on effect (deploy/restart needed), failure modes, and irreversibility leaves the agent under-informed.

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 67%: 'env' and 'project' are documented in the schema, but 'key' has no description at all. The description adds no parameter-level meaning (e.g., whether the key must already exist), so it does not compensate for the partial 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 ('Remove') and resource ('environment variable'), so the action is unambiguous. It does not differentiate itself from siblings such as env.secrets.set or env.secrets.list, and it doesn't clarify that the variable is scoped to a project/environment pair.

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 is given. The obvious alternative, env.secrets.set, is never mentioned, nor is there any indication of prerequisites such as the key already existing or a redeploy being required after removal.

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 scope of data returned and, by framing it as an 'is it running' query, implies a read-only diagnostic, but it never confirms non-destructiveness, permissions required, or cost/latency for a potentially log-heavy call.

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 purpose and then the payload contents. There is no preamble, no repetition, and every clause maps to a concrete returned signal.

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 does the heavy lifting by enumerating the returned diagnostic fields, which is exactly what an agent needs to decide relevance. It stops short of covering prerequisites, permissions, or freshness/pagination of the log tail, leaving a small gap.

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

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

Schema coverage is 100% and both parameters (project, env, with its production/staging/preview semantics) are documented in the schema. The description adds no extra meaning such as default environment, required scoping, or accepted identifier formats, 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?

The description names a concrete action (debug/status) and resource (an environment) and enumerates exactly what the agent gets back: running state, restarts, OOM kills, memory/CPU, live release, and recent log errors. That enumeration distinguishes it in substance from siblings like env.list, env.restart, and env.exec, though no sibling is named 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 only implied: the word 'Debug' plus the list of diagnostic signals suggests calling it when an environment looks unhealthy, but there is no explicit when-to-use, no prerequisite (e.g. must the env exist, does it work on stopped envs), and no routing against alternatives such as logs.query or metrics.get.

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, yet it discloses nothing: not that this is a read-only operation, not whether it requires project access, not pagination or ordering of branches. The phrasing weakly implies a query of existing state, but no concrete behavioral trait is stated.

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

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

The description is short and front-loaded, which is good, but its brevity reflects under-specification rather than efficiency—there is no verb, no scope, and nothing an agent can act on beyond the name. It is not bloated, but it fails to earn its place with useful content.

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

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

For a tool with no annotations, no output schema, and a single required parameter, the description should at least establish that this is a read of branch refs and what the caller gets back. As written it is too thin to let an agent call it confidently or distinguish it from its git 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% for the single 'project' parameter, so the schema already documents the input; per the baseline rule this scores 3. The description adds no additional meaning about what 'project' must reference or how it is resolved.

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

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

The description is a bare noun phrase with no verb: 'Branches and their head commits.' It restates the tool name (git.branches) and only marginally extends it by mentioning head commits, but an agent cannot tell from this alone whether it lists, reads, or creates branches, nor how it differs from siblings like git.log or git.remote.

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 prerequisites, and no mention of any alternative tool. The agent gets no signal about when git.branches is the right call versus git.log, git.remote, or git.revert.

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, yet it only implies a read operation. It fails to state pagination/limit behavior, ordering guarantees, the default branch resolution, or whether a missing branch errors out.

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?

It is a single short fragment with zero waste, which is good, but it is under-specified rather than truly concise. The brevity comes at the cost of useful information an agent needs.

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

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

For a tool with no annotations, no output schema, and a required 'project' parameter plus optional branch/limit, the description is far too thin. It should explain return shape (commit list fields), ordering, and default limits to be callable with confidence.

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

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

With three parameters at 67% schema coverage, the schema already documents 'branch' (default main) and 'project'. The description restates branch scoping and implies recency for 'limit' but adds no default value, range, or format detail, so it contributes little 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 fragment 'Recent commits on a branch' does convey the resource (commits) and implies a listing action, so an agent can roughly infer a git log operation. However, it never uses a clear verb and offers no differentiation from siblings such as git.branches, git.revert, or code.read, leaving selection ambiguous.

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 alternatives like git.branches (to see branch names) or code.read (to inspect file contents). No mention of prerequisites, required project context, or when-not-to-use conditions.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the URL is authenticated and explains the non-obvious consequence that pushing main deploys staging while any other branch creates a preview environment. It does not explicitly cover permissions or safety, but for a getter this is a strong disclosure of relevant 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?

The description is two concise sentences with zero waste. The primary purpose is front-loaded, followed by essential deployment context.

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 getter with one fully documented parameter and no output schema, the description is complete: it explains what is returned (the remote URL) and the practical push consequences. No critical information for correct invocation 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%, so the single 'project' parameter is already documented in the schema as 'Project name'. The description adds no additional meaning about the parameter, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get the authenticated git remote URL for pushing.' It is immediately distinguishable from sibling git tools like git.branches, git.log, and git.revert, which serve different purposes.

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

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

The description implies the tool is used when you need the remote URL for pushing, and it adds contextual detail about branch deployment. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide any exclusions or prerequisites.

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

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

With no annotations, the description carries the full behavioral burden. It discloses a genuinely important trait: the revert creates a new commit that 'deploys like a push,' warning the agent of a deployment side effect. However, it omits auth/permission requirements, reversibility, and whether the operation is destructive.

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 written sentences with zero waste. The core operation is front-loaded and the deploy consequence follows immediately. Nothing is padded.

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 and no output schema, the description is terse but does disclose the critical deploy side effect. It still leaves gaps around permissions, reversibility, and return behavior that an agent invoking a git history rewrite would benefit from.

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 67%, above the low-coverage threshold. The description implies the commit and branch context but adds no format or syntax detail. The required 'commit' parameter has no schema description and is not clarified in the description either, so this is a minimum-viable 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?

The description states a specific verb and resource: 'Revert a commit on a branch server-side.' This clearly distinguishes it as a git-level operation, though it does not explicitly differentiate from the sibling 'rollback' tool, which an agent could plausibly 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?

There is no explicit when-to-use or when-not-to-use guidance. The alternative 'rollback' sibling is never named, and no condition is given for choosing git.revert over it. The only hint is the deploy consequence, which is a side-effect note rather than usage 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?

With no annotations, the description carries the full behavioral burden. It does disclose the response shape and the 8 KB truncation, but is silent on the key risk: the schema accepts arbitrary method and body, so this can execute mutating requests (POST/DELETE) against a named environment including production, and no side-effect, auth, or rate-limit behavior is stated.

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 no wasted words; the capability and its output scope are front-loaded before the usage hint.

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?

Since there is no output schema, the description usefully enumerates return values and the 8 KB cap. However, for a 6-parameter tool with a nested headers object and zero annotation coverage, it omits method defaults and side-effect/authorization context needed to invoke it safely.

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 only 50%: env, path and project are documented in the schema, while method, body, and the nested headers object are not. The description adds nothing about parameter usage — no default method, no header format, no body encoding — 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?

States a specific verb and resource ('Send one HTTP request to the environment from inside Plinth') plus the response payload (status, headers, timing, first 8 KB of body). This clearly separates it from siblings like requests.query or logs.query, though it never names an alternative 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?

'Use it to reproduce a failing route' gives a concrete use context, but there is no statement of when NOT to use it, no named alternative (requests.query, logs.query, env.exec), and no prerequisite or approval conditions for firing a live request at production.

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 usefully discloses the categories of log lines available, but says nothing about read-only semantics, pagination, ordering, default limits, or auth requirements. It adds real content context but leaves operational behavior unstated.

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 resource front-loaded and the filtering capability second; nothing is wasted. It could be slightly more explicit, but the structure is efficient and well-ordered.

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 query tool with no annotations and no output schema, the description is adequate on what it returns but omits how it behaves (ordering, span limits, pagination). An agent can invoke it, but key operational details are 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 coverage is 67%, and the description adds meaning only for grep ('filter by text') and stream ('filter by stream'), while limit and since remain only in the schema. It marginally enriches the schema but does not fully compensate for the uncovered parameters.

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

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

States the resource (logs for an environment) and enumerates the specific line sources it returns (app stdout/stderr, build, cron, system), so an agent can tell it apart from metrics.get or requests.query. The verb is only implied (query/retrieve), which keeps it just shy 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 implies you use this to inspect environment output and mentions two filtering axes, but gives no explicit when-to-use, when-not-to-use, or guidance on choosing it over sibling query tools like metrics.get or requests.query. Usage is inferable only.

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 state the default time window when 'since' is omitted, whether the operation is safe/read-only, what percentiles are returned, or any rate limits or auth requirements. For a metrics endpoint the default window is a real behavioral question the description leaves open.

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 that names the measures without preamble. Nothing is wasted, though the one-sentence form leaves little room for the scoping detail the tool needs.

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, no annotations, and an undocumented 'since' parameter, the description should explain the return shape (which percentiles) and the default time range. It does neither, so an agent cannot confidently invoke it without guessing at the time window.

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 67%: 'env' and 'project' are described in the schema, while 'since' is undocumented in both schema and description. The description's 'for an environment' merely restates the env parameter, adding no format, enum, or default details. Baseline 3 for partial coverage with the description not compensating for the 'since' 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 (get) and resource (metrics) and enumerates the exact measures returned: request count, error rate, and latency percentiles. It is clear what the tool produces, though it never names the likely-overlapping siblings analytics.get or requests.query to differentiate 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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as analytics.get or requests.query. The phrase 'for an environment' implies scoping but tells the agent nothing about which tool to pick for which question.

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 usefully discloses the 'Owner only' authorization requirement and the effect of the setting (approval types run without asking), but omits whether the supplied list replaces or merges with existing policy, whether changes are reversible, and any audit implications for a security-sensitive setting.

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 fragments, front-loaded with the critical 'Owner only' constraint, then purpose, then the value list. No filler and everything an agent needs is near the top.

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-parameter tool with no output schema and no annotations, purpose, auth and allowed values are covered. The significant remaining gap is whether auto_approve is the complete desired set (destructive overwrite) or an additive list, which directly affects correct invocation of a security-relevant setting.

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 single parameter has no enum, so the description must compensate. It does so by enumerating the accepted keys (project.create, project.delete, promote.production, migration.destructive, db.restore.production, billing), which is exactly the value domain an agent needs. It does not clarify array replace-vs-merge semantics, which limits it below 5.

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: setting which approval types run without asking, i.e. the auto-approval policy. This clearly distinguishes it from siblings like approvals.list, approval.status and approval.cancel, which operate on individual approvals rather than the policy. The verb 'choose' is slightly soft but the intent 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?

Usage is implied by 'Choose which approval types run without asking' — an agent can infer this configures auto-approval. However, there is no explicit when-to-use or when-not guidance, and no pointer to related siblings such as approvals.list for inspecting pending approvals.

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 and does substantially: it discloses that this is a multi-resource write (repo, two environments, two databases) and that the operation can be gated by an asynchronous owner-approval flow with a specific follow-up action. It omits auth/permission requirements, failure and rollback behavior, and whether re-invoking with the same name is idempotent.

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, both load-bearing. The resource definition comes first, then the approval-flow caveat, with zero filler or restatement of the tool name.

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 create tool with no annotations and no output schema, the description covers the important non-obvious behavior: the composite resources created and the pending_approval return path with the required agent follow-up. It is nearly complete; only permission prerequisites and error/repeat-call semantics are left unstated.

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% for the single `name` parameter (lowercase, 3-40 chars, with an example), so the schema already documents it fully. The description adds nothing about the parameter; the baseline of 3 applies when the schema does the heavy lifting and the description does not compensate or extend.

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 (project), then immediately defines the domain noun by listing the composite resources produced: a git repo plus production and staging environments, each with its own Postgres database. This lets an agent distinguish project.create from siblings like account.create, project.upgrade, or project.delete without opening any 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?

Gives clear operational context for the conditional path: creation may return pending_approval, in which case the owner must approve via email and the agent should tell the user it is waiting, then poll approval.status. It does not state when to prefer this over alternatives or any prerequisites (e.g., account/plan requirements), so it falls short of full when/when-not 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?

With no annotations provided, the description carries the full burden and discloses critical behavior: irreversibility, the full set of destroyed resources, and the asynchronous pending_approval workflow including owner email and next steps. This is rich behavioral context for a destructive operation.

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

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

The description is three tightly written sentences, front-loading the action and scope before the irreversible warning and approval workflow. Every sentence adds necessary information with 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?

Given no annotations and no output schema, the description is complete for a destructive tool: it covers what is deleted, that the action is irreversible, and the possible pending_approval return plus the required follow-up. Nothing essential is missing for an agent to invoke and handle the result 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 100% and the single project parameter is already documented in the schema as 'Project name'. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb (Delete), the resource (project), and the full destructive scope (repo, environments, databases). This distinguishes it clearly from siblings like project.get, project.list, project.create, and project.downgrade.

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 clear procedural context for the approval flow: it tells the agent to tell the owner it is waiting and then poll approval.status. It does not explicitly compare this tool to alternatives or state when not to use it, keeping it below a 5.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose two concrete consequences — custom domains stop being served and the subscription shrinks with a prorated credit — which is real added value. However, it omits reversibility, whether data is lost, permission/ownership requirements, and confirmation expectations, leaving meaningful gaps for a mutation that changes service availability.

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 the core action, then the two consequences. No filler, every sentence earns its place.

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

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

For a single-parameter tool with no output schema and no annotations, the description covers the action and the two most important side effects. It is close to complete but would benefit from stating reversibility and whether the change is immediate.

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 parameter with 100% schema description coverage ('Project name'), so the schema already carries the semantics. The description adds nothing about the project argument (e.g., accepted identifier format or what happens on an unknown name), 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 plus the target state: 'Move a project back to the free plan.' That target state is what separates it from the sibling project.upgrade, so an agent can route correctly without opening either 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?

Usage is implied by the action (you downgrade when you want to leave the paid plan), and base effects are described, but there is no explicit when-to-use/when-not guidance, no mention of project.upgrade as the inverse alternative, and no stated preconditions such as being on a paid plan.

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. 'Show' correctly conveys a read-only operation and the field list discloses what is returned, which is valuable since there is no output schema. However, nothing is said about behavior for a nonexistent project, permissions, or error handling.

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 zero filler; the verb and scope come first and the returned fields follow as a compact list. 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 single-param read tool with no output schema and no annotations, the description usefully enumerates the returned fields, which compensates for the missing output schema. It stops short of naming the sibling alternative or failure behavior, leaving a small gap.

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

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

With a single required parameter at 100% schema description coverage, the schema already documents 'project' fully. The description adds no format, naming convention, or lookup semantics beyond what the schema provides, 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 ('Show') and resource ('one project'), and enumerates the payload (git remote, environments, live release per environment, URLs). The phrase 'one project' versus the sibling project.list makes the scope distinction clear 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?

The singular 'one project' implicitly signals this is for single-project inspection rather than listing, but it never names project.list as the alternative or states when to prefer it. No prerequisites (auth, project existence) are mentioned; 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?

No annotations are provided, so the description carries the full disclosure burden. It does disclose the shape of the data returned (environments, live releases, URLs), which is more than annotations would give, but says nothing about pagination, account scoping, result limits, or auth requirements for a potentially large collection.

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 verb and resource lead, and the payload detail 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 zero-parameter list tool with no annotations and no output schema, the description is minimally adequate: it names the resource and the key fields returned. It omits scoping (all projects vs. a workspace), ordering, pagination, and when to prefer project.get, which an agent may need to call it correctly.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a parameterless tool applies. The description correctly does not waste words on nonexistent inputs.

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 pairs a specific verb ("List") with a specific resource ("projects") and even enumerates the payload (environments, live releases, URLs), so the agent knows what it gets back. It does not, however, differentiate itself from the nearby project.get, which reads as a similar retrieval of project data.

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 statement of when to use this tool versus project.get or any other sibling, and no prerequisites, scoping, or exclusions are given. Usage is only implied by the verb "List".

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 delivers critical behavioral details: billing timing, prorated charge to the owner, and an asynchronous approval flow. It also discloses the pending_approval return path and directs the agent to inform the user and poll approval.status.

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 tight sentences, front-loaded with the core action and pricing, then billing timing, then the approval edge case. Every sentence adds information an agent needs to invoke the tool and handle its outcome.

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 or output schema, the description covers the most important unknown behaviors: billing, approval workflow, and the non-obvious pending_approval return. It does not explain the normal success return or potential error states, but the critical async path is well documented.

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% for the single 'project' parameter, so the schema already defines it adequately. The description adds no extra syntax, format, or meaning beyond what the schema provides, matching the baseline of 3 for high schema coverage.

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 and resource: 'Move a project to Pro', plus the plan pricing and included benefits. It clearly distinguishes itself from sibling tools like project.downgrade and project.create without needing schema inspection.

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?

It clearly establishes the context for use (upgrading a project to Pro) and implies the alternative is project.downgrade. It also tells the agent what to do after a pending approval result, though it does not explicitly state when to avoid the tool or list prerequisites.

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

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

With no annotations, the description carries the full burden and does well: it discloses the migration side effect, the asynchronous approval outcome, the owner notification, and the correct follow-up call. It omits permissions required and whether the promotion is reversible/rollback-able, which leaves some behavioral 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?

Three tightly written sentences that front-load the core action before the migration side effect and the async approval path. Every sentence carries actionable information with 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 or annotations exist, so the description must cover behavior and largely does: it explains the migration step, the approval branch, and the polling follow-up. Minor gaps remain around what a non-pending success returns and any permission requirements.

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 to, from, and project are already documented in the schema. The description restates the staging/production defaults already present in the schema descriptions, adding no new syntax or constraint information. 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 (promote) and the resource/scope (a release running on one environment to another), with the default direction spelled out. It is clearly distinguishable from siblings like deploy and rollback, which concern getting code out rather than moving an existing release between environments.

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 context and a default (staging to production) plus explicit follow-up behavior when the call returns pending_approval (tell the owner, poll approval.status). It does not explicitly contrast with deploy or state when promotion is inappropriate, so it stops short of full when/when-not 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 disclosure burden. It does disclose the shape of the returned records, which is the key behavioral fact for a read query, but says nothing about default result limits, default time window, ordering, or pagination behavior despite a limit and since parameter 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 tight sentences with no filler, and the what-it-returns content is front-loaded before the filtering hint. Efficient, though it could be slightly denser about defaults.

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 describes the return record fields, which is a genuine contribution. It remains incomplete on defaults for limit/since and on the environment's time window, which matter for correct invocation of a recent-requests query.

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 only 33%, so most parameters are undocumented in the schema. The description compensates for two of them by explaining min_status (failure filtering at 500+) and path, but adds no meaning for limit, since, or project.

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 resource (recent HTTP requests to an environment) and enumerates the fields returned (method, path, status, time taken), so an agent knows exactly what it fetches. It does not explicitly distinguish itself from the closest siblings logs.query or metrics.get, which keeps it out of 5 territory.

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?

"Filter to failures with min_status 500, or by path" is a concrete usage hint that tells the agent how to narrow results for error investigation. However, there is no guidance on when to pick this over logs.query, metrics.get, or http.probe, 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.