BotKelp

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context the annotations cannot: the key itself is never returned, and identity is resolved from the MCP transport rather than the call. It also discloses the return shape (yes/no plus linkage timestamps). It does not mention error or unauthenticated-transport behavior, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the answer the tool returns, then the privacy guarantee, then usage and the no-parameter note. Every sentence carries distinct information with no padding.

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

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

There is no output schema, but the description compensates by describing what is returned (linked yes/no and when it was last linked/rotated) and confirming the key value is never exposed. Combined with the annotations covering the safety profile, an agent has everything needed 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?

Zero parameters, so the baseline is 4, and the description earns that by explaining why there are none — identity comes from the MCP transport, not the call. That preempts an agent trying to pass an account identifier.

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+resource (reports whether the authenticated account has an account_api_key linked) plus the extra payload (last linked/rotated timestamps). It is clearly distinguishable from the surrounding get_*/set_* configuration siblings, which deal with pagesets, github, projects, and scaffolds rather than account key state.

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 an explicit when-to-use: 'check whether key-gated tools will work before calling them.' That is actionable routing guidance. It stops short of naming a specific alternative tool or stating when-not to call it, so it is clear but not exhaustive.

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 is covered. The description adds genuinely useful context beyond that: the auth prerequisite ('requires a linked account (transport auth)') and what the returned data actually represents (file trees baked into a dedicated forked repo).

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

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

Two sentences, no filler, and the dual-mode behavior is front-loaded before the supporting detail about the forked repo and auth. Every clause carries 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 one-parameter read tool with full schema coverage, no output schema, and annotations covering safety, the description supplies everything needed: both return shapes, the mode selector, the auth requirement, and the downstream relationship to purchase_scaffold.

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 parameter's description already says 'omit to list set names instead', so the description largely restates the schema. It adds no format, casing, or matching semantics for the name value 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 description names a specific verb and resource ('Lists this account's admin page set names') and gives the exact dual behavior — list names when name is omitted, return a set's files when name is passed. It also frames the resource concretely as the file trees that purchase_scaffold bakes into a forked repo, which separates it from sibling setters like set_adminpageset.

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 states the condition that selects each mode (omit name to list, pass name to fetch) and ties the resource to purchase_scaffold's admin_page_set param, so the agent knows where this data flows. It does not explicitly name set_adminpageset as the mutating alternative or state when not to use this tool, so it stops short of full 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 cover the read-only/idempotent/non-destructive profile, yet the description adds hard-to-guess traits: a rate limit of 32 calls/day, the auth precondition (registered account key, no credits spent), and the critical output caveat that files contain raw EJS markers and are not build-ready. That is exactly the context annotations cannot supply.

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 core purpose, then cost/limits, then the build-readiness caveat as the emphasized closing point. Slightly long and mildly repetitive (the EJS warning and the 'do not copy' warning say related things), but every element is actionable and nothing is padding.

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 full schema coverage and sibling alternatives, nothing needed to call it correctly is missing: cost, limits, auth, output nature, and correct follow-up tools are all stated.

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 already includes an id@version example, so the schema does the work. The description adds no syntax or format detail beyond it; baseline 3 is appropriate.

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

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

States a specific verb (returns) and resource (exact, unrendered source files for one catalog component) and immediately scopes it against the purchased scaffold equivalent. An agent can distinguish this from get_scaffold, purchase_scaffold, and generate_scaffold 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-to-use ('inspect or compare a component before buying a scaffold') and explicit when-not with named alternatives ('Use purchase_scaffold or generate_scaffold for rendered, build-ready files', 'Do not copy get_component output directly into a project'). The routing decision is fully determined.

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 cover readOnly/idempotent/openWorld, so the description adds the important non-obvious behavior: an unconnected account returns an installUrl, and granting access requires the GitHub App install tied to a signed-in account. It stops short of describing pagination or listing limits.

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

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

Three tight sentences, front-loaded with the core capability before the conditional remediation flow. 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?

With no output schema, the description does the necessary work by sketching the return shape (connection status vs. file list, plus installUrl when unconnected). Complete enough for correct invocation, though error or empty-repo behavior is 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 100% and the single path parameter is already documented as 'Omit for connection status.' The description reinforces this dual-mode behavior but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific dual-mode purpose: report whether a GitHub repo is connected, or list files under a path in that repo. The verb+resource is unmistakable and clearly distinct from set_github among 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?

Gives explicit mode selection (omit path for connection status; supply path to list files) and a prerequisite workflow (sign in with GitHub before installing). It does not explicitly name sibling alternatives like set_github, but the read-vs-write distinction is evident from the name pair.

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, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered structurally. The description adds value annotations don't carry: 'Free, no API key' (auth/cost profile) and the concrete return shape (TSV with named columns). It does not mention rate limits or response size, so it stops short of a 5.

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

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

Three short sentences, no filler. The scoping fact ('Free, no API key') and the output contract are front-loaded, and the call-ordering directive follows immediately. 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?

No output schema exists, but the description compensates by naming the exact TSV columns the agent will receive, and it covers cost/auth and call ordering. For a zero-parameter discovery tool this is wholly sufficient to invoke 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 per the rubric the baseline is 4. The description's mention of TSV columns is output metadata rather than parameter semantics, and there is nothing further for a description to clarify here.

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: it returns usage plus a full component catalog in TSV form, and enumerates the exact columns (id, name, version, description, provides, requires, conflictsWith). This is far more specific than the sibling 'get_component' or 'get_scaffold' and lets an agent know exactly what it gets.

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 says 'Call this first,' which is a prescriptive ordering instruction, and offers an alternative route ('Prefer resource botkelp://catalog if your client supports it') with the condition that selects it. This is the when/when-not/alternative pattern at full strength.

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 bar is low. The description adds non-obvious context the annotations cannot: that no project_api_key argument is required, which removes a likely agent mistake.

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

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

Two sentences, zero waste. The primary purpose (what is listed and what fields come back) is front-loaded, with the downstream routing note second.

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 compensates by enumerating the returned fields (id, name, description, repo, components, maintain state), and it covers the auth question. Nothing an agent needs to call this zero-parameter tool 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 are no input parameters, so the baseline is 4. The mention of 'projectid' is an output field used by a sibling tool, not a this-tool parameter, and it is described clearly enough.

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 ('Lists this account's saved scaffold projects') and enumerates the returned fields, so the agent knows exactly what it retrieves. It also distinguishes itself from get_scaffold by explaining the re-fetch path, so no sibling confusion remains.

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 routes the agent onward ('use the projectid with get_scaffold to re-fetch a scaffold'), giving clear follow-up context. It does not state explicit when-not-to-use conditions for this tool, but none are really needed for a zero-argument list 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 declare it is not read-only, idempotent, non-destructive and open-world, but the description adds the substantive context annotations cannot convey: no additional credit cost, the Maintain-subscription precondition, the x402 exemption, and the token cost of inline delivery. Nothing here contradicts the annotations (readOnlyHint=false is consistent with a tool that mints a fresh clone credential).

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 what the tool does and the no-cost guarantee, then moves to preconditions and delivery modes. The dense em-dash phrasing and parenthetical asides make some sentences heavy, but 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?

For a 3-parameter tool with no output schema, the description covers the return shape (a git clone command vs. files in the reply), the credit implication, and the authorization preconditions. An agent has everything needed 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining that projectid is resolved from the authenticated account and by framing delivery as a token-cost tradeoff rather than just an enum. The site_profile guidance largely restates the schema, so it is not a full 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 and resource ('re-fetches a scaffold you already purchased') and immediately distinguishes itself from the sibling purchase_scaffold by naming the prior-purchase precondition. An agent can tell it apart from purchase_scaffold and verify_scaffold 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?

Explicitly scopes use to scaffolds already purchased, names the originating tool, and lays out the conditional gates (active Maintain subscription required for credit-flow projects; no gate for x402/accountless projects) with a pointer to set_projects. It also names the alternative path implicitly by framing this as a repeat hand-off rather than a purchase.

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 cover read-only/idempotent/no-destruction, so the description's added value is the auth prerequisite ('linked account (transport auth)'), the payload-vs-file distinction, and the 'no second unsolicited reply' note that tells the agent not to wait for a follow-up. It stops short of describing pagination termination or the cursor lifecycle beyond the next.arguments hint.

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 outcome, then mode selection, then the scaffold-continuation case, then the auth caveat. Dense and largely waste-free, though the accumulation of parenthetical asides ('default: all', 'transport auth') slightly taxes readability.

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

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

With no output schema, the description carries the burden of the return shape and does so ('JSON bodies + destination paths'), plus auth and the incomplete-result continuation path. Minor gaps remain on what a cursor-terminated or error response looks like, but an agent has enough to invoke 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%, so the baseline is 3, but the description adds real semantics the schema doesn't: field's default of all, the list-vs-name fetch modes, and the mapping of cursor to next.arguments from a prior incomplete scaffold result. That linkage is the kind of meaning the schema alone cannot convey.

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 ... this account's named site profiles') and immediately scopes what it is not ('not as files in a template repo'), which separates it from get_scaffold/purchase_scaffold. The enumerated categories (privacy, terms, cookies, licence, custom_field) sharpen the resource further.

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 mode selection ('Pass list: true to see profile names, or siteprofilename to fetch one') and cross-tool routing: on an incomplete purchase_scaffold/get_scaffold result, call this with next.arguments. An agent can pick the right call path without 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 declare a non-read-only open-world operation, and the description adds substantial behavioral context beyond them: private repo ownership, short-lived clone credential, persistent projectid, reuse of repos for repeat component combinations, no charge for failed builds, and payment handling details. It does not contradict annotations.

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

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

The purpose is front-loaded and the dense operational detail is relevant for a complex purchase tool. However, the single long paragraph with many parentheticals and nested conditions makes it harder to scan than necessary.

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 seven parameters, no output schema, and a complex payment/build flow, the description covers return values, build behavior, payment modes, and edge cases sufficiently for an agent to call the tool 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%, so the baseline is 3. The description still adds meaning beyond the schema in places, such as explaining that extra pages land in the clone, that shared templates stay generic, and that site_profile bakes dashboard legal pages, though some payment and maintain details overlap with schema descriptions.

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?

Starts with a specific verb and resource: 'Requests a build for the given component ids.' It explains the backing GitHub repo ownership and return artifacts, and explicitly routes later use to get_scaffold/get_projects/set_projects, distinguishing it from sibling retrieval 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?

Provides explicit conditional guidance: use 'inline' only when a shell isn't available, use site_profile for the account's single or named profile, call get_siteprofile if incomplete, and choose credit versus x402 payment flows. These are concrete when/when-not and alternative-path instructions.

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

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

Annotations only flag this as a non-read-only, open-world, non-idempotent write. The description goes well beyond that by disclosing the linked-account requirement (spam guard), a concrete rate limit (10 calls/day per account), and a safety constraint (never include API keys or secrets). That is exactly the extra behavioral 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?

Purpose, target URL, and eligibility come first, followed by the requirements and constraints. The 'Welcome — we want agents to report problems instead of silently papering over them' clause is motivational filler, but the rest of the text is dense and 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 fire-and-forget issue-filing tool with no output schema, the description supplies everything an agent needs: where the issue goes, what qualifies, the account requirement, the rate limit, and the no-secrets rule. Nothing material 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 both parameters are already documented, including 'Optional project id this report relates to.' The description's note that projectid is optional context and its secrets warning largely restate the schema, adding little new semantics. 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 (file) plus the resource (GitHub issue) and the exact target URL, then scopes the content: generated/catalog code problems or component/docs change requests. No sibling tool does anything comparable, so an agent can select it unambiguously.

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

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

Gives clear context for when to use it — reporting problems with generated or catalog code, or requesting component/docs changes — and frames the intent ('report problems instead of silently papering over them'). It stops short of naming when-not-to-use or an alternative channel, so it falls one step below the top.

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; the description reinforces this by saying it 'fully replaces' a named set, which tells the agent existing content is overwritten. It adds the file-source detail but doesn't state permission requirements or what happens to files omitted from the new set.

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 verb and resource, then adds two supporting sentences that earn their place by disambiguating from purchase_scaffold and clarifying the file-based nature. Slightly more context than strictly necessary, 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?

With only two parameters, full schema coverage, and annotations carrying the safety profile, the description is nearly complete. It could say more about the replace semantics for omitted files and whether a prior set must exist, but nothing critical 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 both 'name' and 'files' (with example paths) are already documented in the schema. The description adds only the notion of 'one named set' and the multiple-sets-per-account note, which is contextual rather than syntactic. Baseline 3 applies 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 ('Creates or fully replaces one named admin page set for this account') and distinguishes itself from the sibling get_adminpageset by scope. The added 'real file source (React/Next.js), not text config' clarifies what the resource actually is, which an agent could not infer from the name alone.

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

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

Gives clear context for when this tool is relevant by contrasting it with purchase_scaffold (which bakes a set into a new repo), and notes an account may hold multiple named sets. It stops short of an explicit when-to-use/when-not statement or naming a preferred alternative for the replace case.

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 declare destructiveHint=true and idempotentHint=true, but the description doesn't explain the destructive nature (dropping the repo connection), confirm idempotency, or clarify openWorld implications. It mentions 'disconnect: true drops the connection' which aligns with destructiveness, but lacks deeper context like permissions, reversibility, 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?

Reasonably concise but includes extraneous workflow details (purchase_scaffold template_files) that confuse the tool's own scope. Front-loads the core action, but the second sentence about purchase_scaffold is tangential.

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 is simple (1 param, no output schema), so the description covers the basic usage. However, it misses important behavioral aspects like authentication requirements, error conditions, or what happens on repeat calls, and the integration with siblings is only partially explained.

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

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

The single parameter 'disconnect' is fully described in the schema (coverage 100%). The description adds minimal extra meaning ('drops the connection'), which is consistent with the schema. Baseline 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?

Clearly states it returns a GitHub App install URL for granting repo access and can disconnect. The purpose is understandable, though it's somewhat muddled by mixing in a workflow with purchase_scaffold. Not fully explicit about what the tool itself does versus surrounding steps.

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 a sequence: open URL, pick repo, approve, then run purchase_scaffold. Suggests signing in with GitHub first. However, it doesn't clearly distinguish when to use this tool versus get_github, and the guidance is tangled with another tool's invocation.

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 declare destructive=true and idempotent=false, and the description meaningfully extends that by clarifying that turning Maintain off neither deletes nor revokes anything already cloned and only stops future repeat get_scaffold access after the current billing period. It does not disclose reversibility of key rotation or permission requirements, so it stops short of a 5.

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

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

Two dense sentences, front-loaded with the primary action and then the scoping and consequence caveat. No filler, though the second sentence is long and mixes the maintain semantics with billing nuance.

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 non-idempotent, destructive mutation with no output schema, the description covers what changes, what is NOT affected, and the account scoping of projectid. Missing only the return shape and whether rotation can be undone.

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 supplies meaning for the one undocumented parameter: 'maintain' is explained as turning Maintain on/off. It also confirms projectid is account-scoped, matching the schema. No syntax or defaults are added beyond that.

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 specific verbs (turns Maintain on/off, rotates project key) and the resource (one of this account's projects), which is enough to separate it from sibling get_projects and get_scaffold. The term 'Maintain' is product-specific jargon that an agent must infer, keeping it 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 implied rather than stated: you call it to toggle Maintain or rotate a key, and the effect of turning Maintain off is explained. There is no explicit when-to-use framing, no guidance on pairing with verify_scaffold or purchase_scaffold, and no named alternative.

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. The description adds merge semantics beyond those hints: omitted fields are preserved (or blank for a new profile) and custom_field is merged key-by-key, which tells the agent how partial updates 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?

Three sentences, front-loaded with the upsert action, then the update semantics, then the multi-profile context. 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?

With no output schema, a nested `field` object, and a destructive annotation, the description supplies the needed merge/partial-update behavior and notes that multiple named profiles can coexist. It leaves the destructive aspect implicit, but the practical calling guidance is 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 the baseline is 3, but the description adds real meaning: the partial-update contract for `field` and the key-by-key merge for custom_field go beyond the schema's generic 'omitted fields keep their current value' note.

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 pair (creates or updates) plus the resource (one named site profile) and scopes it to this account. An agent can distinguish it from the sibling get_siteprofile at a glance.

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 call guidance: pass only what changed, omitted fields retain saved values, and custom_field entries merge key-by-key. It does not explicitly say when to prefer this over get_siteprofile, but the read/write split is obvious from the verb.

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 cover the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false), and the description adds substantial non-obvious behavior: the two-call WAIT/jobId polling protocol, the one-to-two-minute runtime, that every build is attributed to a real customer, and that FAIL returns the tail of the failing step 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?

Front-loaded with the core action and protocol, then prerequisites and failure handling. Dense and mostly waste-free, though the final FAIL-handling sentences could be tightened slightly.

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 complex asynchronous two-phase tool with no output schema, the description covers the call protocol, timing, required provenance, failure output, and the retry loop — everything an agent needs to invoke and recover 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%, so the baseline is 3, but the description adds real meaning beyond the schema: `files` must be the FULL project (not just changed files), and `projectid` must belong to a purchased project. It also explains the jobId polling pattern, though it does not elaborate on envVariables beyond what the schema says.

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 — runs a real `npm install && npm run build` on an isolated GitHub Actions runner and reports build success. It is clearly distinguishable from siblings like get_scaffold (retrieval) and purchase_scaffold (acquisition).

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 says to use this after editing a get_scaffold result and before handing it to the user, and that it requires a projectid from a prior purchase_scaffold. It also names the alternative artifacts (get_scaffold, purchase_scaffold, get_component's envVariables) that feed into it.

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