Bunstation

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds one useful piece of context beyond that — the result is scoped to the authenticated user rather than an arbitrary account — but says nothing about caching, freshness, or auth failure behavior.

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

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

A single front-loaded sentence that identifies the actor, the two returned artifacts, and nothing else. Every word earns its place.

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

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

For a zero-argument read with full annotation coverage and an output schema describing the return shape, the description is essentially sufficient. A minor gap is that it does not say whether the plan and balance are returned in one object or what units the balance uses, but the output schema covers that.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description correctly implies no input is needed by framing the result as belonging to the authenticated user.

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 ('Return') plus two named resources ('credit balance', 'current subscription plan'), which cleanly separates it from account_invoices_get and account_usage_get. It stops short of explicitly contrasting itself with those siblings, so it is clear but not maximally 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 statement of when to call this versus account_usage_get or account_invoices_get, and no mention of preconditions or follow-ups. The usage is inferable from the purpose, but the description provides no guidance text at all.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully carried by structured data. The description adds only the shape of what comes back (invoice plus hosted Stripe URL), and says nothing about scoping, auth, or misses on unknown ids.

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 return payload and the parameter sourcing both front-loaded. Nothing could be removed without losing 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?

With an output schema, rich annotations, and a fully described single required parameter, the definition covers what an agent needs to call it correctly. Only minor context, such as behavior on an unknown or foreign id, is 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 coverage is 100% and the single parameter is already documented as 'Invoice UUID returned by account_invoices_list'. The description's 'Use the id from account_invoices_list' restates that provenance rather than adding new semantics, 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 ('Get one invoice') and adds the distinguishing payload ('its hosted Stripe URL'), which clearly separates it from the sibling account_invoices_list that returns many. An agent can pick between the two 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 tells the agent to source the id from account_invoices_list, which encodes the intended list-then-get workflow. It does not state exclusions or error cases, but for a single-object getter the applicable context is essentially covered.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral facts that are not in the annotations and cannot be inferred cheaply: results are ordered 'newest first', and 'amounts are in major currency units' prevents the caller from interpreting amounts as cents. It does not say what happens when the limit is reached or whether there is more data beyond the returned page.

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

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

Two short sentences with no padding. The scoping and ordering information is front-loaded, and the currency-unit caveat follows immediately where it is needed.

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 output schema is present, so the return shape needs no explanation in the description, and the ordering and unit conventions are covered. For a one-parameter list tool whose read-only safety profile is already covered by annotations, the only real gap is pagination or truncation behavior.

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

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

The schema has 100% description coverage: the single 'limit' parameter is fully documented with its default and its max of 50. The description adds nothing about that parameter, so the baseline score is 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 uses a specific verb and resource ('List the authenticated user's invoices'), and it scopes the results to one user. That scope alone distinguishes it from the other account_* siblings, but it never names account_invoices_get, the tool for retrieving a single invoice, so the caller must infer from the description that 'get' returns one invoice while this tool returns a list.

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

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

Only implied usage: listing invoices for the authenticated user. There is no statement of when to prefer this over account_invoices_get, no note that pagination or a limit is the way to get more results, and no exclusion conditions. The name largely carries the routing decision.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful output context ('Includes a total and recent log rows') and default date behavior, but does not go much further.

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 purpose and followed by the date_range values, default, and output shape. Every sentence earns its place and 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?

The tool has an output schema, so return values do not need full explanation, and all parameters are fully documented in the schema. The description is adequate for a simple read-only usage tool, though it lacks explicit when-not guidance.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters in detail. The description repeats the date_range enum and default but adds no extra semantics for page or limit beyond what the schema provides.

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

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

States a specific verb and resource: returns token usage for the authenticated user. It is distinguishable from siblings like account_credits_get and account_invoices_get, though it does not explicitly call out those distinctions.

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 'returns token usage for the authenticated user', but there is no explicit guidance on when to choose this tool over account_credits_get or account_invoices_get, nor any conditions 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds the meaningful ordering trait ('newest first'), which is not in the annotations, but says nothing about volume, truncation, or whether all builds or only recent ones are returned.

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 with the ordering trait front-loaded and no wasted words. It is efficient, though perhaps too terse for the ambiguity it leaves unresolved.

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?

Low-complexity single-parameter read with an output schema and rich annotations, so not much is required. Still, 'recent' is unexplained (how many? is there a default window?) and the builds/commits terminology mismatch is not resolved, leaving minor gaps an agent would want filled.

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

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

Schema coverage is 100% with a single required project_id fully documented, so the schema does the heavy lifting. The description's 'for a project' merely echoes the parameter without adding format or scoping detail beyond 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 (list builds for a project) plus ordering (newest first), which is concrete. It does not differentiate against the very similar sibling projects_builds_log, and the title's 'commits' vs. the description's 'builds' leaves the resource slightly 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?

No guidance on when to use this rather than projects_builds_log, projects_get, or projects_changes_list. The closest sibling is left entirely unaddressed, so the agent must infer selection from names alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no restatement. The description adds only the fallback behavior for an omitted commit, and says nothing about what a build log contains, its size, or failure modes for a commit with no build.

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

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

Two short sentences, front-loaded with the action and followed by the default behavior. No filler, though the extreme terseness leaves useful context unstated rather than being a model of efficient completeness.

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 low-complexity, two-parameter read tool with full schema coverage, an output schema, and complete annotations. The description covers the one behavioral decision an agent must make (omit commit_id or supply one), so nothing essential 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 100%, and the schema itself documents that commit_id is an optional UUID defaulting to the latest commit. The description restates that default without adding syntax, format, or edge-case guidance, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Read the build log') with clear scope limitation to a commit. An agent can distinguish it from projects_builds_list, though the description never names that sibling explicitly, so differentiation is inferred rather than stated.

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?

'Defaults to the latest commit' implies a usage pattern for the common case where no commit is supplied. However, there is no statement of when to prefer this over projects_builds_list or how to obtain a commit_id in the first place, leaving routing to inference.

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

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

Annotations already declare non-read-only, destructive, and idempotent, so the safety profile is covered structurally. The description adds the useful constraint that ALL pending changes are committed rather than a selected subset. It omits whether the commit is reversible, whether it pushes/deploys, or what the response reports.

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

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

Two short sentences, front-loaded with the action and scope, with zero filler or redundancy.

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

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

For a two-parameter tool with full schema coverage, annotations, and an output schema, the description covers what is needed to call it correctly. A brief note on reversibility or whether the commit publishes/deploys would round it out.

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

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

Schema coverage is 100%, and the schema already documents the optional message with its default and maxLength, plus project_id. The description adds nothing about the message default or the meaning of project ownership, so baseline 3 applies.

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

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

States a specific verb ('Commit') and resource ('every pending file change in a project'), so the operation and its bulk scope are unambiguous. It does not name the sibling it complements (projects_changes_discard) or contrast with it, 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?

'Call this after editing files' gives a clear precondition for when to invoke it. It offers no explicit exclusions or alternatives — e.g. that discarding instead uses projects_changes_discard — so it is clear context without routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is carried structurally. The description adds the useful scoping fact that committed content survives, but never states that the discarded change is unrecoverable or what happens on a clean path.

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 the resource, with zero filler. Nothing in it could be cut without losing 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?

An output schema exists and annotations cover the destructive and idempotent profile, so the description need not explain returns. Still, for an irreversible discard operation, the description is thin on failure modes (nonexistent path, uncommitted vs staged mismatch) and recovery expectations.

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 project_id and path are already documented in the schema, including the staged-change semantics of path. The description's "one ... file change" only loosely implies the single-path parameter and adds no format or constraint 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?

Uses a specific verb ("Drop") on a specific resource ("one uncommitted file change") and adds scope clarification ("keep the committed file"). It is clearly distinct from projects_changes_commit and projects_changes_list, though it does not name those siblings explicitly.

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

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

No when-to-use context, no prerequisites, and no comparison to projects_changes_commit, which is the natural alternative an agent must choose between. The agent must infer from the name alone that this is the revert-style operation.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds the meaningful behavioral qualifier 'uncommitted', which tells the agent what subset of files is returned, but it says nothing about ordering, diff inclusion, or whether staged/unstaged/untracked are all included.

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 with the key qualifier ('uncommitted') front-loaded and no filler. Nothing is wasted or buried.

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

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

With rich annotations, full schema coverage, one required parameter, and an output schema defining the return shape, the definition is nearly sufficient. A brief note on which change states are included and on failure modes for unknown projects would make it 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?

The single project_id parameter is fully documented in the schema (UUID of a project owned by the authenticated user), so the schema carries the burden. The description adds no extra meaning such as what happens for a nonexistent or unauthorized project, so the high-coverage 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?

The description names a specific verb ('List') and resource ('uncommitted file changes for a project'), which separates it from projects_files_list since it scopes to uncommitted state. It does not, however, explicitly name its nearest siblings (projects_changes_commit / projects_changes_discard) to sharpen the boundary.

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 alternatives such as projects_files_list or the commit/discard siblings, and no stated prerequisites. An agent must infer the workflow context 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?

Annotations already declare that this is a safe, read-only, idempotent operation. The description adds useful behavioral context by specifying that it exposes recent conversation, whether generation is running, and queued follow-ups. It does not discuss pagination or message-depth limits.

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

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

The description is a single front-loaded sentence that gives the core action and returned information without filler. Every phrase contributes directly to understanding 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?

For a one-parameter read tool with rich annotations and an output schema, the description is complete enough to invoke it correctly. It covers the main content scope, and output details are delegated to the existing 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?

There is one required project_id parameter, and the schema describes it fully with UUID format and ownership constraints. The description does not add further parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: read the recent conversation for a project. It also names additional returned information: generation status and queued follow-ups. This clearly distinguishes it from sibling tools such as projects_generation_stop and projects_get.

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

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

The description implies usage by stating what the tool reads, but it does not explicitly say when to use it versus alternatives or when not to use it. Since there is no direct chat sibling in the list, the implied scope is adequate but not rich.

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

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

Annotations already mark this as a non-read-only, non-destructive, non-idempotent mutation; the description goes well beyond that by disclosing the hard limit of 3, the fail-silent behavior ("this tool creates nothing"), and the default stack/model applied when omitted. The mention that it starts building the project also flags an asynchronous side effect the annotations cannot express.

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?

Defaults and the core action are front-loaded, and the limit is stated before the do-not-call instruction, which is the right order. The point is stated twice ("If it is greater than 3, this tool creates nothing" and "Do not call this tool when the user asked for more than 3 projects"), a mild redundancy that costs a little tightness.

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

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

Return values need no explanation because an output schema exists, and the description covers defaults, the hard cap, and the requested_count semantics. The one notable omission is what happens after creation, i.e., that the build is asynchronous and progress is tracked via projects_builds_list, which an agent would need to close the loop.

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: it clarifies that requested_count is the count from the *current message* and instructs "Pass the real number," explaining why a single-project tool takes a count at all (it is a guard that fails when >3). It also restates the defaults for stack and model, which the schema already lists, so it is at the top of the useful range rather than beyond 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?

It states a specific verb and resource ("Create one Bunstation project from a prompt and start building it"), plus the immediate side effect of kicking off a build. It does not distinguish itself from sibling creation paths such as templates_use, which also appears to produce projects, so an agent must infer that difference.

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 an explicit exclusion: "Do not call this tool when the user asked for more than 3 projects," and additionally prescribes what to do instead (tell the user the maximum is 3). The conditions that select this tool versus not calling it are stated outright rather than implied.

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

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

Annotations already establish write, non-destructive, idempotent behavior. The description adds real value by explaining that the file stays uncommitted until projects_changes_commit, but it omits what happens if the path already exists (overwrite vs error), which matters for an idempotent create.

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

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

Three short, front-loaded sentences with no filler; the staging constraint and path base each earn their 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 3-parameter create with an output schema present, the description covers the essential workflow (staging, commit dependency, path base). It only lacks collision behavior for an existing path.

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 100% schema coverage the baseline is 3, and the description earns an extra point by clarifying that 'path' is relative to the project root – meaning the schema does not itself supply.

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 ('Stage a new text file') that clearly separates it from siblings like projects_files_update, projects_files_delete, and projects_files_read. It doesn't explicitly name those siblings, so it stops short of a 5, but the action is unambiguous.

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

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

It names the follow-up tool (projects_changes_commit) and implies the staging workflow, which gives useful context. However, it never says when to use this versus projects_files_update for an existing file, or that it's only for new files.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true; the description adds the crucial qualifier that nothing is actually destroyed until commit, which materially changes how an agent should reason about the risk. It stops short of explaining how to revert the staged change.

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 deferred-effect warning front-loaded right after the action. Nothing is redundant with the title.

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 an output schema, full annotation coverage, and fully documented parameters, the description only needs to explain the staged-mutation semantics, which it does. A brief note on how to undo or what happens to a nonexistent path would close the remaining gap.

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

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

Schema description coverage is 100%, with both project_id and path documented inline, so the description carries no parameter burden. It adds no syntax or format detail beyond the schema; 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 (stage deletion) and resource (a file) and immediately makes the staging/commit distinction that separates it from projects_changes_commit and projects_files_update.

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 'stays uncommitted until projects_changes_commit' clause tells the agent this is step one of a two-step workflow and names the sibling that finalizes it. It does not mention that projects_changes_discard is how you back out, so the reverse path is left implicit.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety bar is low. The description still earns credit by disclosing that results include uncommitted creates and deletes — a working-tree semantics detail the annotations cannot express and that materially changes how an agent interprets the output.

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

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

A single sentence, front-loaded with the core action and immediately qualified by the scope detail that matters most. 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?

Output schema covers the return shape and annotations cover side effects, so the description only needs to add scope, which it does. Minor gaps remain (ordering, behavior for invalid project_id), but nothing an agent needs in order to call it correctly is missing.

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

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

Only one parameter and schema coverage is 100%, with ownership and UUID format spelled out in the schema itself. The description adds nothing about project_id, so baseline 3 applies.

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

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

States a specific verb and resource ('List file paths in a project') and scopes the result to paths plus the uncommitted state. It does not explicitly distinguish itself from the nearby projects_files_search or projects_files_read siblings, 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?

Usage is only implied: an agent can infer this is the enumeration tool versus search/read, but the description never says when to pick this over projects_files_search or what happens if the project is empty or unknown.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond them: the read reflects uncommitted changes, meaning the result may diverge from committed state — a fact no annotation or schema conveys.

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 most decision-relevant nuance (uncommitted changes) is placed where it will be read first.

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?

Output schema exists, so return-value explanation is unnecessary, and annotations carry the safety profile. Only minor gaps remain, such as path resolution semantics and what happens for a nonexistent path.

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 project_id (owned-project UUID) and path are fully documented in structured fields. The description adds nothing about path resolution relative to the project root, so baseline 3 applies.

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

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

States a specific verb (read) and resource (a project text file), and adds the nontrivial detail that it returns uncommitted working-tree content when present. It does not name the near-sibling projects_media_read, so the text-vs-binary distinction must be inferred from the word 'text'.

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

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

No explicit when-to-use guidance, no prerequisites, and no alternatives named. An agent must infer that media_read covers binary assets and files_list covers directory enumeration purely from the one word 'text'.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description goes further by disclosing the data source semantics — it searches uncommitted changes and falls back from a running live preview to the committed repository — which materially affects result trust and is not in any structured field.

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, and the capability statement is front-loaded ahead of the source-resolution caveat.

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?

An output schema exists, so return values need no explanation, and the schema fully documents parameters. What remains distinctly the description's job — which corpus is searched and how staleness is handled — is answered directly.

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 query, project_id, whole_word, case_sensitive, and max_results all carry their own documentation and defaults. The description adds no extra meaning about matching rules or limit behavior, 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 ("Search text in a project") plus a distinguishing scope note about uncommitted changes. An agent can tell this apart from projects_files_read or projects_files_list by the text-search framing, 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?

The description implies when to use it (finding text across a project rather than reading a known file), but never states when to prefer projects_files_read or projects_files_list instead, nor any exclusions or prerequisites beyond the project ownership implied by the schema.

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

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

Annotations already declare destructive=true and idempotent=true, so the safety profile is covered. The description adds genuinely new context beyond annotations: the change is staged/uncommitted until projects_changes_commit, which is critical for an agent to understand the delayed-effect model.

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 zero filler, and the core operation is front-loaded ahead of the commit dependency.

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?

An output schema exists and all params are documented, so return values and inputs need no explanation. The staging model is covered; only the interaction with sibling change tools is slightly under-explained for a destructive, staged-mutation tool.

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

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

Schema coverage is 100%, so all three parameters are documented in the schema itself. The description reinforces the 'complete replacement' semantics of content, but adds little beyond what the schema descriptions already state.

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 ('Stage a full replacement') and resource ('existing text file'), and 'existing' implicitly distinguishes it from projects_files_create. An agent can tell this is an overwrite operation versus a create 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?

The description implies when to use it ('full replacement of an existing text file') and points to the follow-up commitment step (projects_changes_commit). However, it gives no explicit when-not guidance or contrast with sibling tools like projects_files_create or projects_changes_discard.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds essentially nothing beyond those annotations — it doesn't say whether partial output is discarded or retained, whether the stop is graceful or immediate, or how long it takes to take effect.

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 with the action front-loaded and zero wasted wording. The brevity is appropriate for a simple stop operation, though there is room for one more sentence of useful 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?

An output schema exists and the single parameter is well documented, so the description needn't explain return values. However, for a destructive mutation tool, it omits outcome semantics (state of the stopped project, idempotency behavior on repeat calls) that would make the definition 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% and the single project_id parameter is fully documented as a UUID of an owned project. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Stop') and resource ('the generation currently running on a project'), so the agent knows exactly which operation this performs. No sibling tool shares this purpose, so explicit differentiation isn't necessary, but the description stops short of mentioning what 'generation' produces.

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

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

There is no guidance on when to call this versus other tools, no prerequisites, and no statement about what happens if no generation is running. The agent must infer timing and conditions entirely.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely useful constraint not in the annotations – the project must be owned by the authenticated user – but says nothing about what happens on a non-owned or missing project_id.

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 nine-word sentence with zero waste, front-loaded with the operation and resource. Nothing is repeated from annotations or 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?

An output schema exists, so return values need not be explained, and the single parameter is fully documented. For a simple read tool with rich annotations this is close to complete; only the pointer to projects_list as the alternative would meaningfully improve it.

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

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

Schema description coverage is 100%, and the project_id property is documented as a UUID belonging to the authenticated user, so the schema carries the semantics. The description's only addition is restating the ownership constraint, which the schema already contains; 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 pairs the verb 'Get' with a specific resource ('one project') and a clear scope ('the authenticated user owns'), so an agent can tell this is a single-resource read apart from projects_list. It does not name the list sibling explicitly, so differentiation is implied rather than stated.

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: an agent can infer this is for retrieving a single known project rather than enumerating them. There is no explicit 'use this instead of projects_list' guidance, no stated prerequisites beyond ownership, and no exclusion 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — result ordering by newest activity — but says nothing about pagination, page size, or result caps, which matters for a list endpoint.

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

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

A single sentence that front-loads the action, resource, scope, and ordering with zero filler. Nothing could be removed without losing 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?

With an output schema present and no input parameters, the description needn't explain return values or argument formats. What remains thin is listing behavior (pagination/limits), which is the only real gap for a list tool.

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

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

The tool takes zero parameters, so per the baseline this dimension sits at 4. The schema is empty and fully described; there is nothing further the description could clarify about 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?

States a specific verb (List) and resource (Bunstation projects) plus scope (authenticated user's) and ordering (newest activity first). It implies the distinction from projects_get via 'list', but never names a sibling to differentiate against 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 the verb 'List' and the ordering note. There is no explicit when-to-use vs when-to-use-projects_get or projects_changes_list guidance, nor any prerequisite or exclusion 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?

Annotations already declare readOnly/idempotent/non-destructive, so the description's added value is elsewhere: it discloses result ordering (newest first) and two non-obvious semantic gotchas — mime_type is inferred from the filename rather than authoritative, and used_bytes is account-wide rather than project-scoped. That account-wide caveat is exactly the kind of context annotations cannot carry.

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 and ordering, then the disambiguation, then the two field caveats. Nothing is repeated from the schema and no sentence 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?

Output schema exists, so return values need not be enumerated, and the annotations cover the safety profile. The description still adds the ordering, the sibling disambiguation, and the two field-semantics caveats an agent needs to interpret results 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 coverage is 100% and all three parameters (project_id, page, limit) carry their own descriptions with defaults, so the schema already does the heavy lifting. The description adds nothing about parameter behavior such as what happens when page exceeds the result set — baseline 3 is 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?

Specific verb+resource: lists files in a project's media library, newest first. It also explicitly rules out a confusable sibling by stating 'These are uploaded assets, not source files', which lets an agent distinguish this from projects_files_list 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 'uploaded assets, not source files' clause gives clear context for choosing this over the source-file listing tools, and the newest-first ordering hints at feed-style use. It stops short of naming alternatives (projects_files_list, projects_media_read) or stating exclusions explicitly.

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

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

Beyond the read-only annotations, the description discloses concrete behavioral details: 4 MB size thresholds, image and text return behavior, and URL-only fallback for larger files. These are operationally important return-value traits not captured by annotations alone.

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 tight sentences with no waste. The core action is front-loaded, followed by the most important return-behavior 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?

For a simple single-file read with complete annotations and a full output schema, the description provides enough context to call the tool correctly. It covers purpose, size constraints, and return-type behavior.

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

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

Schema coverage is 100%, so both project_id and media_id are already well documented in the schema. The description adds the concept of a media library but does not add syntax or constraints 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: preview one file from the project media library. It clearly distinguishes the single-file read from listing or uploading, though it does not name sibling tools explicitly.

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

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

The phrase 'Preview one file' implies the intended use, but the description does not explicitly contrast this tool with projects_media_list or projects_media_upload. Usage is inferable 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?

Goes well beyond the annotations, which only say this is non-read-only, non-destructive, and non-idempotent. The description discloses the one-time token model, a 10-minute expiry, that one token permits exactly one request, and how to batch multiple files via additional -F media=@path arguments — all operationally critical details absent from structured fields.

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

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

The core constraint (no file bytes, returns a curl command) is front-loaded, and every following sentence adds a distinct operational fact: file-path substitution, where the URL appears, batching, retry, expiry. No sentence is redundant with another or with 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?

The tool has an output schema, so return values need no explanation, and the description instead covers the full two-step workflow an agent must execute — the only real complexity here. Nothing needed to invoke it correctly is missing.

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

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

There is a single parameter (project_id) and schema description coverage is 100%, with the schema already stating it must be a UUID of a project owned by the authenticated user. The description adds no parameter-level detail, so the baseline 3 applies rather than a higher score.

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 ('Prepare an upload into the project media library') and immediately distinguishes itself from write-style siblings by declaring 'This does not accept file bytes.' An agent can tell this apart from projects_files_create or projects_media_read 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 explicit when-and-how: call this first, then run the returned curl command with __FILE__ replaced. It also names concrete anti-patterns ('do not base64-encode', 'do not put file contents in this tool') and a retry path ('If the upload fails, call this tool again'), 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?

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is available elsewhere. The description adds useful defaulting behavior for commit_id and subdomain, but does not explain what happens to any existing published site when republishing.

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 compact sentences with the main action front-loaded. Both sentences convey relevant information without 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?

With a rich input schema, an output schema, and annotations covering safety and idempotency, the description is mostly complete for invoking the tool. A stronger definition would explicitly mention that publishing replaces or affects the currently published subdomain.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the input schema. The description restates the default behavior for commit_id and subdomain but adds no syntax or constraint details beyond what the schema provides.

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

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

The description states a specific verb and resource: publish a successful build on a bunstation.app subdomain. It clearly distinguishes this deployment action from sibling tools such as projects_builds_list or projects_get.

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

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

The description implies usage by saying it publishes a successful build, so an agent can infer it should be used after a successful build exists. However, it provides no explicit when-not conditions or named alternatives such as projects_builds_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?

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral nuance — the model change applies to 'later messages'/'later project generations', implying existing content is unaffected — but it never explains why the operation is flagged destructive or what is irreversible, leaving the strongest annotation unexplained.

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 enumerates both capabilities with no filler, hedging, or redundant restatement of the title. Every clause carries 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 three-parameter update with full schema coverage, an output schema, and complete annotations, the description covers both mutable fields and hints at the effect on future generations. Only minor gaps remain — partial-update semantics and the reason for the destructive flag — which are low-impact 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 `name`, `model`, and `project_id` are already fully documented, including format and length constraints. The description only loosely restates that `name` is a rename and `model` affects future generations; it adds no constraint, default, or interaction detail beyond the schema, 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 specific verb and resource ('rename a project', 'change the model') and enumerates exactly the two mutable fields, which maps cleanly onto the `name` and `model` properties. It is clearly distinct from `projects_files_update` and `projects_create` by virtue of operating on project-level settings, though it never explicitly 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?

The two stated operations imply when to reach for this tool (renaming, switching model), but there is no explicit 'use this instead of X' routing and no mention of prerequisites such as project ownership or whether both fields can be changed in one call. Usage is inferable 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds real value with ordering ('newest first') and the fact that results mirror the public templates page, but says nothing about result volume, pagination, or whether the list is 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 short sentences with the key information (what, scope, ordering) front-loaded and zero preamble. The final sentence re-uses the schema's own examples, which is mild redundancy but not harmful.

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?

One optional parameter, full schema coverage, an output schema handling return shape, and annotations covering safety. The description supplies the ordering guarantee and source scope, which is the remaining information an agent needs to call this 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 coverage is 100% and the single optional 'category' param is fully documented in the schema, including slug examples. The description's category sentence merely restates the schema example ('restaurant or landing_page') without adding matching behavior such as case sensitivity or unknown-slug handling.

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

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

States a specific verb and resource ('List public templates from the Bunstation app library') and adds the source scope plus ordering ('newest first'). It doesn't explicitly distinguish itself from projects_list or the sibling templates_use, and 'Same projects as the templates page' is a loose analogy rather than a contrast.

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 'public templates' scope and the category-filter mention imply a browse-then-pick workflow, so an agent can infer this is the discovery step before templates_use. However, no sibling is named and there is no statement of when not to use it (e.g., vs. projects_list), so guidance remains implied.

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

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

Annotations already state that this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds useful behavioral detail by explaining that the template repository is copied, a new owned project is created, and no prompt build starts.

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 definition is brief and front-loaded: it states the core operation first, then clarifies the remix behavior and the required parameter source. Every sentence contributes useful 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?

With one fully described parameter, annotations covering safety and mutability, and an output schema present, the description supplies the remaining context an agent needs. The no-prompt-build caveat is especially helpful for selecting and interpreting 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?

The single template_id parameter is fully documented in the schema as a UUID from templates_list. The description repeats the source of the ID but adds no further syntax or format detail beyond the structured 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 gives a specific verb and resource: copy a public template into a new project for the authenticated user. It also distinguishes this operation from template listing by naming templates_list as the source of the required ID.

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

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

It clearly positions this as the app-remix flow and says to obtain the template_id from templates_list. It does not explicitly exclude other project-creation or build-starting alternatives, but the intended context is clear.

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