brewpage-mcp

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

Annotations declare readOnlyHint=false and destructiveHint=false, so mutation-vs-read is already covered. The description usefully adds the admin-token authorization requirement, but says nothing about whether an existing binding is overwritten, whether the operation is idempotent, or what happens on failure.

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

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

Two short sentences with zero filler, and the resource is front-loaded. The unexplained '(as publish)' is the only wasted or confusing token.

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, no nested objects, and no output schema, the description covers purpose and the authorization prerequisite. Only conflict/idempotency behavior for a mutation is left implicit.

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

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

Schema description coverage is 100%, so both 'token' and 'ownerToken' are already documented, including the BREWPAGE_OWNER_TOKEN default. The description's mention of the owner/admin token distinction only restates what the schema says, 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: adding an owner token to a BrewPage profile. The parenthetical '(as publish)' is unexplained and slightly muddies the intent, but the core operation is unambiguous.

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

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

The precondition 'Needs an admin token of that profile' signals the required authority and implies this is for binding rather than minting. However, it never distinguishes this from sibling tools like mint_token, which an agent could easily confuse with it.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds the owner-token requirement and resource types, but it does not clarify irreversibility, dependent-resource effects, or confirmation behavior.

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

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

The description is a single front-loaded sentence with no wasted words. It presents the core action and the required credential context immediately.

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

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

For a destructive delete tool with full schema coverage and destructiveHint=true in annotations, the description is nearly complete. It could still say more about irreversibility or post-delete behavior, but no critical invocation detail 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 parameter meanings are already documented. The description reinforces the resource types and owner-token usage, but adds no syntax or format details 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: delete a BrewPage resource, and it enumerates the supported resource types. It is clear what the tool does, though it does not explicitly differentiate itself from sibling mutation tools such as update_html or republish_site.

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

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

The description gives an implied use case by saying 'Delete', but it provides no explicit guidance on when to use this tool versus alternatives. The owner-token mention is an authentication prerequisite, not a usage-routing guideline.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is the 'published' scope constraint. It does not address password-protected access behavior, error responses, or whether unpublished drafts are reachable, all of which would be useful for a fetch-by-ID call.

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

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

One sentence with no filler, and the verb plus keying are front-loaded. It is perhaps slightly under-specified rather than padded, so it lands just under the top mark.

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

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

For a simple read-only lookup with a fully described 3-parameter schema, readOnlyHint, and no output schema to explain, the description covers what an agent needs to make the call. Only the protected-document and not-found paths are left unstated, a minor 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%, so namespace, id, and password are already documented structurally. The description mentions namespace and ID by name but adds no format, case-sensitivity, or password-handling semantics 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 gives a specific verb ('Fetch') and resource ('BrewPage JSON document') plus the keying ('by namespace and ID'), which is enough to separate it from get_page and get_kv. It stops short of explicitly contrasting with those siblings, keeping it below 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: the word 'published' signals the document must already be published, which is real guidance, but there is no statement of when to choose this over get_page, get_kv, or search_gallery, and no mention of prerequisites or failure modes.

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

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

readOnlyHint=true already declares the safety profile, so the description is not required to establish that this is a read. However, it adds nothing beyond restating the read: it does not say what happens if the key is missing, how password-protected stores behave, or whether the raw value is returned verbatim.

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 resource and lookup dimensions come first and nothing is repeated.

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

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

For a simple read with full schema coverage and readOnlyHint present, the basics are covered. But there is no output schema, and the description never characterizes the returned value (raw string? JSON? null on miss?) or error behavior for a wrong password, leaving a real gap for the calling agent.

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

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

Schema description coverage is 100%, so all four parameters (namespace, id, key, password) are already documented in the schema. The description echoes the three required ones but adds no format, casing, or scoping meaning, so the baseline of 3 applies.

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

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

Specific verb (fetch) plus resource (a value from a BrewPage KV store) and the three identifying dimensions used to locate it. It is clearly distinguishable in intent from set_kv/publish_kv, but it never names those siblings explicitly.

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

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

The description states only what the tool does; there is no guidance on when to use it, no mention of the write counterpart (set_kv), and no note that the optional password is needed for protected stores. Retrieval-only usage is implied by the verb 'fetch', but nothing is 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 only supply readOnlyHint=true; the description adds real behavioral context beyond that, namely that output is byte-denominated ('Sizes are bytes') and that setting BREWPAGE_OWNER_TOKEN conditionally adds reach and ownerMaxTtlDays fields. That conditional-environment behavior is exactly the kind of thing an agent could not infer from the schema or 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?

Purpose is front-loaded with the endpoint named in parentheses, the returned-field list follows, and the actionable 'call it before publishing' guidance closes it. The middle enumeration is long but each item substitutes for the absent output schema, so little is wasted.

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

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

With no output schema and no parameters, the description carries the full explanatory load and does so by enumerating the returned fields plus the conditional token-dependent additions. An agent knows what it will get back and when to invoke it, with no material gaps.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly signals that no input is required by framing the environment variable as affecting output rather than as an argument.

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

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

States a specific verb and resource ('Get the current BrewPage upload limits') and then enumerates exactly what is returned (request size, file counts, ZIP expansion, TTL, extensions, skipped system files). An agent can immediately tell this apart from the publish_* siblings, which the final sentence reinforces.

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 when to call it: 'Call it before publishing a large or multi-file site,' which links it to publish_site/publish_file. It stops short of naming when not to call it or pointing at an alternative for other pre-flight needs, so it is clear but not fully 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=true, so the safety profile is covered; the description adds genuinely non-derivable behavior: that protected pages are unlocked via the password header, and that what is returned is the stored/rendered artifact rather than original source. It omits return shape details but the read-only semantics are unambiguous.

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, with the core operation ('Fetch ... by namespace and ID') front-loaded. The second sentence carries real information (the exclusion plus the password-header behavior) rather than restating 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 only three simple parameters, 100% schema coverage, and a readOnly annotation, the description is nearly complete. The gap is the return shape: 'rendered HTML or format-specific code/text' is loose and there is no output schema to pin down structure, but this is minor for a simple read 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 namespace, id, and password are all documented in the schema already. The description reinforces the namespace/id lookup and notes password applies to protected pages, matching the schema's own wording without adding format or validation detail, 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+resource ('Fetch stored rendered HTML or format-specific code/text') and the lookup key ('by namespace and ID'). It explicitly excludes two similarly-worded endpoints (owner-only original-source, browser viewer), though it does not distinguish itself from content-oriented siblings like get_json or get_kv, so differentiation is partial.

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

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

Gives a clear usage context ('This reads API content') and names what it is not for ('not the owner-only original-source endpoint or browser viewer'). It stops short of routing the agent to the sibling tools that would serve those excluded cases, so no full when-not-with-alternatives 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?

The readOnlyHint annotation already establishes that this is a safe read operation, and the description adds meaningful context by documenting the disjoint count invariant and the tz fallback semantics. It does not cover auth or rate limits, but for a simple stats endpoint the added behavioral detail is strong.

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 front-loaded sentences with no filler: purpose and included metrics, the count invariant, and the tz behavior. Every sentence earns its place.

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

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

For a simple read-only stats tool with one fully described optional parameter and no output schema, the description covers the key metrics, count semantics, and tz behavior. It could say slightly more about the response shape, but it is complete enough to call correctly.

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

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

Schema description coverage is 100%, so the tz parameter is already fully documented in the schema. The description restates that tz shifts the 'today' boundary and defaults to UTC, but adds no syntax or format detail 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: get BrewPage platform-wide usage statistics, including page count, file count, and storage usage. It is clearly a stats-reading tool, though it does not explicitly differentiate itself from nearby siblings such as get_limits.

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 'platform-wide usage statistics' and the mention of the tz parameter, but there is no explicit guidance on when to use this tool versus alternatives like get_limits. No exclusions or decision criteria are provided.

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

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

Adds real value beyond the annotations: the new token is shown only once (a non-recoverable disclosure), and admin scope 'can manage tokens' is a privilege escalation detail an agent must know before choosing scope. Annotations only cover the mutation/safety profile.

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 action and its prerequisite, with no filler. Slightly compressed to the point that the expiry wording omits the per-scope default rule, but nothing is wasted.

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

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

For a token-minting mutation with no output schema, the description covers the critical facts: prerequisite admin token, one-time display of the secret, and scope/expiry choices. Complete enough to call correctly, though it omits whether minting is reversible or what happens to existing tokens.

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

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

Schema description coverage is 100%, so every parameter including default resolution rules ('admin 90d, publish never') is already documented. The description restates the enum values but adds nothing new for `label` or `ownerToken`; 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 ('Mint a new profile token') plus the prerequisite actor (admin token). It does not explicitly distinguish itself from the sibling bind_token, which is the one tool an agent could confuse it with, so it falls short of a 5.

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

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

Gives clear calling context: you need an admin token, and scope/expiry defaults are spelled out. There is no explicit when-not guidance or reference to the alternative bind_token, so exclusions are missing.

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?

Adds substantial context beyond annotations: default size limits (5 MiB for files/audio, 20 MiB for video), the fact that it returns a share link, owner token, and a private manageUrl, plus critical handling instructions to never publish the manageUrl. Also discloses secret-flagging behavior in notices. This is rich, specific behavioral detail.

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 upload action and keeps overall length short, but is written as choppy fragments and includes a potentially misleading 'private namespace + password' clause that costs clarity. Some sentences earn their place (manageUrl warning, size limits); others (the password fragment) confuse.

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

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

With no output schema, the description usefully covers return values (share link, owner token, manageUrl) and limits, which is what an agent needs to invoke and handle results. The one gap is the unclear password workflow for secrets, but otherwise it is complete for a mutation tool with full annotation coverage.

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 five parameters (url, filename, namespace, ownerToken, deliveryMode) are already well documented in the schema, including the detailed namespace semantics. The description adds the constraint that password/TTL are intentionally absent, but largely restates what structured fields provide. 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+resource: 'Upload a file to BrewPage via URL.' The 'file' resource plus 'via URL' implicitly distinguishes it from publish_html, publish_json, publish_kv and publish_site, though no sibling is named explicitly. An agent can identify what it does without opening the schema.

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

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

Offers some context: use private namespace for secrets, and notes that password/TTL inputs are not exposed. However, 'For a secret: private namespace + password' is confusing because password is explicitly not an input, leaving the agent unsure how to actually set one. No guidance on when to prefer this over the sibling publish_* tools.

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

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

Goes well beyond the annotations: states the 5 MiB default limit, that the response carries a share link, owner token and private manageUrl, the sanitization allowlist applied to Markdown, and the auto-subdomain promotion with deliveryModeReason. It also warns explicitly never to publish manageUrl and notes secrets are allowed but flagged.

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 and return shape are front-loaded, and the density is justified by the tool's complexity. A few clauses are terse to the point of being cryptic ('Secrets allowed; likely ones are flagged in notices') but there is little outright waste.

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

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

With nine parameters and no output schema, the description carries the return contract itself (share URL, owner token, manageUrl, expiresAt, deliveryModeReason) and covers the privacy and sanitization behaviors an agent needs before calling. Nothing essential is left to guesswork.

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 parameters are already fully documented in structured fields. The description restates the same features (password, TTL, filename, showTopBar, deliveryMode) without adding syntax or edge-case meaning the schema lacks, which is the baseline-3 case.

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 ('Publish HTML or Markdown content to BrewPage') and implicitly separates itself from publish_json/publish_file/publish_site by naming the content types it accepts. It never names those siblings or points to update_html for edits, so an agent must infer the boundary from 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?

There is real conditional guidance for secrets ('private namespace + password') and for sharing results ('Always share the returned URL', give manageUrl privately), but nothing says when to choose this over update_html, publish_site or publish_file. Usage context is implied rather than spelled out.

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

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the default size cap, that a share link and owner token are returned, and critically that manageUrl is private and must never be published. It also notes secrets are allowed and flagged in notices. It stops short of explaining what happens to an existing publication or what notices look like in full.

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?

Dense but front-loaded: the core action and limit come first, followed by return values, the privacy warning, and secret handling. Parentheticals are compact and each sentence carries actionable information, though the prose is terse to the point of feeling compressed.

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 correctly compensates by naming the returned share link, owner token, and manageUrl. Combined with 100% schema coverage, an agent has what it needs to call the tool, though the create-vs-return-existing-publication behavior is only alluded to indirectly through deliveryMode's schema text.

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 seven parameters, including TTL clamping and namespace rules. The description adds only a little beyond that ('For a secret: private namespace + password', the 1 MiB default), 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 ('Publish a JSON document to BrewPage') and the accepted input shapes (object, array, or JSON-encoded string, including scalars/null). The resource-based naming makes it trivially separable from siblings publish_file, publish_html, publish_kv, and update_json.

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

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

Implied usage comes through conditions like 'For a secret: private namespace + password' and the default 1 MiB limit, but the description never names an alternative or says when to pick publish_json over update_json (to modify an existing document) or publish_kv. An agent must infer tool routing from the name alone.

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

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

Beyond the annotations, the description discloses important behavior: repository limits, the reserved `hosting` key, returned share link and owner token, and the private manageUrl that must never be published. It does not clarify overwrite/conflict behavior when publishing an existing key, which is a notable remaining gap for a write tool with destructiveHint=false.

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 front-loaded with the core action and then layers in limits, return values, and secret-handling guidance without filler. Every sentence contributes operational information.

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

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

For a tool with eight parameters and no output schema, the description is largely complete: it explains key return values, defaults, limits, and sensitive output handling. It still leaves some ambiguity around the `id` component of the addressing tuple and behavior when a key already exists.

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 eight parameters in detail. The description adds some holistic meaning, especially around secrets and namespace choice, but does not add substantial per-parameter semantics 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: publishing a key/value entry to BrewPage and creating a KV store. It explains the addressing tuple and key constraints, but does not explicitly distinguish this creating tool from sibling tools such as set_kv or get_kv.

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

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

The description gives contextual guidance for secrets: use a private namespace plus password. However, it does not explicitly say when to use publish_kv versus set_kv, get_kv, or other sibling tools, leaving the create-vs-update distinction 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?

Goes well past the annotations (which only say not read-only, not destructive) by disclosing concrete limits (25 MB request, 200 files, 5 MB/file, 20 MB total, 380-char paths), silent skip behavior for system files and unsupported extensions with notices, the entry-resolution fallback chain, and a full error-code map (400/413/422). It also flags security handling: `manageUrl` is private and must never be published, and secrets should use private namespace plus a password.

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

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

Front-loads the action and the two usage shapes before the constraint details, and nearly every clause carries operational information (limits, skips, errors, secret handling). It is one dense run-on block, though — the error-code and secrets sentences could be broken out for faster scanning.

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 of describing returns (primary link, `manageUrl`, `expiresAt`) and failure modes, which is what an agent needs to call and recover from this 8-parameter tool. Minor gap: TTL clamping behavior is only described in the schema, and the response shape beyond those named fields stays implicit.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already explains `ttlDays`, `deliveryMode`, `namespace`, and `ownerToken` in more depth than the description does. The description adds real value only for `entry` (fallback chain: explicit entry, else root index.html, else shallowest HTML) and restates the `entryContent`/`files` exclusivity that the schema already declares.

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 ('Publish an HTML site to BrewPage') and immediately splits the two supported shapes (single-page via `entryContent`, multi-page via `files`). It does not, however, differentiate itself from close siblings such as `publish_html` or `republish_site`, so an agent must infer the boundary on its own.

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

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

Clear conditional guidance for the two main modes and for public vs private namespace ('Use it for anything meant to be found or shared', 'never put secrets... there'), plus a pointer to `get_limits` for current values. It stops short of naming alternatives — nothing says when to prefer `republish_site`, `update_hosting`, or `publish_html` instead.

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 the description fully explains the destruction semantics: files absent from the bundle are removed, matching files overwritten, expiry preserved despite ttlDays. It also discloses limits, skipped system/unsupported files, entry resolution, and specific error codes (400, 409, 413, 422), going far beyond 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?

Dense but well front-loaded: purpose first, then replacement mechanics, entry rules, limits, and errors. A few clauses repeat schema-provided details (e.g., ttl ignored, mutual exclusivity), so it is slightly longer than strictly necessary, but there is little waste.

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

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

For a destructive tool with no output schema, the description covers replacement semantics, auth (owner token), limits, skipped file handling, entry resolution, expiry preservation, and the full error taxonomy. An agent has everything needed to invoke it correctly and anticipate outcomes.

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 baseline is 3. The description adds meaningful semantics: entry falls back from entry to root index.html to shallowest HTML file, and files/entryContent are alternatives for multi- vs single-page sites. Some content (ttl ignored, mutual exclusivity) repeats schema descriptions, keeping it from a 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 (republish, full-replace) and resource (existing multi-file BrewPage site) with scope (in place, SAME URL/ID). This clearly distinguishes it from publish_site, which presumably creates a new site, and from update_* 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?

Explicitly distinguishes single-page (entryContent) vs multi-page (files) usage and notes owner token requirement and that old publications are read-only. It does not explicitly name publish_site as the alternative for new sites, but the 'existing ... in place' framing makes the boundary clear.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds that results are limited to the public gallery and that 'mine' is owner-scoped and token-gated, which is useful context, but it says nothing about result volume, ranking, or what happens when no token is supplied with 'mine' true.

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

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

Two short sentences, purpose front-loaded, filters summarized in a single clause. No filler or repetition of schema detail.

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

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

For a read-only, fully documented, zero-required-parameter search with no output schema, the definition covers what the tool does and the notable 'mine' gating. It stops short of describing result shape or behavior when the owner token is missing, which would complete 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 coverage is 100%, so the schema already explains every parameter including the enum, page bounds, and the ownerToken default. The description merely summarizes the filter set without adding format, ranking, or combination semantics 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 ('Search the BrewPage public gallery'), making the operation immediately identifiable. No sibling tool competes for this use case, so it doesn't need explicit differentiation, but it also doesn't distinguish public-gallery scope beyond the phrase 'public gallery'.

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

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

Lists the optional filters and notes that 'mine' requires an owner token, which implies usage context. However, it never states when to use this tool versus other retrieval siblings (get_page, get_json) or what kinds of content are searchable.

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 description adds useful behavioral context beyond the annotations: owner token is required, the `hosting` key is reserved, and old publications fail with 409 OLD_PUBLICATION_READ_ONLY. The annotations already mark this as destructive and non-read-only, and the description does not contradict them.

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 three sentences, front-loaded with the core action, and every sentence contributes a distinct operational constraint. There is no redundant or filler content.

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

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

For a destructive KV write with full schema coverage and annotations covering mutation safety, the description is largely complete: it covers the action, auth, reserved key, and a key failure mode. A minor gap is that it does not explicitly describe the success response or whether an existing value is overwritten beyond the phrase 'Set or update'.

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

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

Schema coverage is 100%, so the schema already documents all five parameters, establishing a baseline of 3. The description adds meaningful semantics for the `key` parameter by stating that `hosting` is reserved, and it reinforces that an owner token is required.

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: set or update a key in an existing BrewPage KV store. It is clearly a write operation on a KV entry, but it does not explicitly name sibling alternatives such as get_kv or publish_kv to sharpen the distinction.

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 usage context is implied by 'Set or update a key in an existing BrewPage KV store' and the owner-token requirement. It also states one when-not condition: old publications are read-only. However, it does not explicitly route the agent between this tool and alternatives like get_kv or publish_kv.

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 and destructiveHint=false, so the mutation profile is covered. The description adds genuine value by noting the change hits both gallery and sitemap and that the publication link is unchanged, a key reversibility/non-destructive detail not in the 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?

Two compact sentences, front-loaded with the action, and the 'Link unchanged' clause earns its place as a behavioral note. Zero waste.

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

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

For a mutation tool that has full schema coverage and safety annotations, the description is nearly complete. It omits auth/ownership requirements and error behavior for non-public IDs, but those are minor given the enum already restricts 'type' to public-listing types.

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 'listed' documented as false=hide/true=show and type constraints given in the enum. The description adds no parameter meaning beyond what the schema already states, 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 (hide/show) and resource (publication) with the concrete effect on gallery and sitemap. It clearly distinguishes the toggle action from sibling publish_*/update_* tools, though it doesn't name a sibling 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 effect implies when to use it (toggling listing), but there is no explicit when/when-not or condition that separates it from alternatives like publish_*. Prerequisites such as the publication being public or caller ownership are 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?

Goes well beyond the annotations, which only say non-read-only and non-destructive: it discloses auth requirements, optimistic-concurrency semantics ('Mismatches are reported, not rejected: a stale version still applies'), preserved state ('OLD links or forced subdomain modes stay unchanged'), and that results carry a delivery notice. It also clarifies that content updates do not alter hosting, preventing a common misuse.

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 scope constraint and prerequisite before behavioral caveats, and every clause carries information. The semicolon-chained single block is dense but not padded.

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

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

For a 6-parameter mutation with annotations but no output schema, it covers auth, versioning, side effects, and the notice in the result. Minor gaps remain: what a 'delivery notice' contains and what happens on invalid enum or missing token are unstated.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including expectedVersion's stale-value behavior. The description's 'pass the current hostingVersion when known' merely restates that, so baseline 3 applies with no meaningful additional parameter semantics.

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

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

States the specific verb and resource ('Change delivery mode') and immediately bounds the target with exclusions ('not a site, not a non-public HTML-format page'), which separates it from publish_site and the publish_* family 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 a clear when-to-use context plus explicit when-not exclusions and a prerequisite ('Requires owner token'), but never names an alternative tool for the excluded cases (e.g. republish_site or update_html), 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?

Goes well beyond the annotations by disclosing that link and delivery mode never change on update, that an advisory deliveryModeReason/notice may come back, and the exact 409 error code for pre-5-October-2026 publications. That is exactly the operational context an agent needs before calling a destructive write.

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 purpose and precondition, followed by immutable-field and error behavior. Four sentences with little waste, though the deliveryModeReason sentence is dense and slightly ahead of its importance.

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?

Without an output schema, the description correctly states it returns updated page metadata, and it covers auth, immutability, advisory notices, and the read-only failure mode. Only the failure behavior for invalid content/format is unmentioned.

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%, including detailed format enumeration and the ownerToken default, so the schema carries the parameter burden. The description only restates the owner-token requirement and adds no format or content semantics 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 and resource ('Update an existing BrewPage HTML/Markdown page'), which implicitly scopes it away from update_json or the publish_* family. It does not name a 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?

It establishes prerequisites (owner token) and a hard exclusion (old publications are read-only with 409 OLD_PUBLICATION_READ_ONLY), which is useful. However, it never says when to use this instead of publish_html, update_json, or other siblings, leaving the main routing decision 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 the tool as destructive and non-read-only, so the description adds useful context: owner-token auth, accepted input shapes, and a specific 409 OLD_PUBLICATION_READ_ONLY failure mode. It does not state whether the update replaces the entire document or what is returned, but against the destructive hint it discloses the main operational constraints.

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, then the auth requirement, input shapes, and an edge-case error. Every sentence carries useful information without 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?

Given the rich schema, destructive annotation, and absence of an output schema, the description covers auth, input forms, and a key read-only constraint. It leaves minor gaps around replacement semantics and error behavior for missing tokens/documents, but is sufficient to call the tool correctly in most cases.

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 input schema already documents namespace, id, json, and ownerToken. The description reinforces the accepted JSON forms and owner-token requirement, but adds no syntax, defaulting behavior, or validation detail beyond the schema.

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

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

States a specific verb and resource: update an existing BrewPage JSON document. The word 'existing' helps distinguish it from the publish_json sibling, but it does not explicitly mention alternatives or the full update semantics.

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

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

Prerequisite information is given ('Requires owner token') along with a hard version exclusion (old publications are read-only). However, the description never explicitly says when to choose update_json over publish_json or how to handle a missing/expired document, so usage is implied rather than fully guided.

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