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

No annotations are provided, so the description carries the full burden. It mentions the owner-token requirement, which is useful, but says nothing about whether deletion is permanent, whether dependent data (KV entries, JSON collections) is destroyed, what happens if the resource doesn't exist, or what the response looks like. For a destructive mutation with zero annotation coverage this is a significant gap.

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

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

A single tightly written sentence with the verb and resource front-loaded and no filler.

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

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

This is a destructive, four-required-parameter tool with no annotations and no output schema, so the description should disclose irreversibility, failure modes, and effects on stored data. It covers only what the parameters already imply, leaving an agent under-informed before an irreversible action.

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 are already documented in the schema; baseline is 3. The description adds only that the token is used for authorization and reiterates the resource-type set, which is already visible in the enum.

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

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

The description states a specific verb (Delete) and resource (BrewPage resource) and enumerates the four resource types, which map exactly to the `type` enum. It does not explicitly contrast itself with siblings, though the delete operation is naturally distinct from the get/publish/update siblings listed.

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

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

No guidance on when to use this versus alternatives, no prerequisites, no warning about irreversibility, and no note that a mistaken delete cannot be undone. Usage is only implied by the verb in the name.

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

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

With no annotations, the description carries the full safety/behavior burden. It does disclose the meaningful constraint that only published documents are fetchable, but it says nothing about password-protected documents (a third parameter exists for this), error behavior for missing or unpublished IDs, or what form the payload takes.

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 keys come first. It is arguably too terse for a tool with an optional auth-ish parameter, but nothing in it is wasted.

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

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

For a simple three-parameter read tool with no annotations and no output schema, the essentials are present, but the description leaves open how the JSON is returned and how protected documents behave. A reader can call it correctly but not predict its failure modes.

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% (id, namespace, password all documented), so the baseline is 3. The description restates the two required keys but adds no meaning beyond the schema, and the optional password parameter is not mentioned at all.

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 (Fetch), the exact resource (published BrewPage JSON document), and the lookup keys (namespace and ID). The 'JSON document' qualifier distinguishes it from the page/kv siblings, though it never names an alternative explicitly.

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

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

There is no statement of when to use this tool versus get_page, get_kv, or search_gallery. The only implicit hint is the word 'published', which suggests drafts are not retrievable here, but no condition or exclusion is 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?

No annotations, so the description carries the full burden. It conveys only that this is a read, but says nothing about behavior when the key is missing (error vs null), authentication for protected stores, or any rate/size 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?

A single front-loaded sentence with zero waste. Nothing redundant, and the identifying parameters come before any qualifiers.

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

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

With no annotations, no output schema, and an optional password parameter, the description should explain what is returned and how protected stores behave. It leaves the return shape (raw string vs JSON value) and error conditions entirely undocumented.

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 defines all four parameters including the optional password. The description merely echoes three of them and omits password, adding no meaning beyond the schema; baseline 3 applies.

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

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

Specific verb 'Fetch' plus resource 'value from a BrewPage KV store' and the identifying trio of namespace/ID/key. It is distinguishable from set_kv and publish_kv by the read verb, though no sibling is named explicitly.

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

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

No guidance on when to use this versus get_json, set_kv, or publish_kv, and no prerequisites stated (e.g., that a password is needed for protected stores). The agent must infer everything from the name.

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

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

No annotations exist, so the description must carry the load, and it does: it discloses the underlying endpoint (GET /api/limits), that no auth is required, and that all sizes are in bytes. It stops short of any statement about caching or freshness of the limits, but the essential behavioral profile is covered.

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

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

Front-loads the purpose in the first clause, then the payload enumeration, then closes with the action directive. The enumeration is dense but every item is a distinct returned field the agent would otherwise not know about.

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 must describe the return surface itself, and it does so field-by-field, plus auth status and units. Nothing an agent needs to decide whether and how to call this 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?

Zero parameters, so the baseline of 4 applies. The description adds unit semantics ('Sizes are bytes') that would otherwise be ambiguous, which is more than an empty 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 (get) and resource (current BrewPage upload limits) and enumerates exactly what is returned: request size, file counts, sizes, ZIP expansion, path/name lengths, TTL, allowed extensions, skipped system files. No sibling tool (publish_*, get_stats) could be confused with this one.

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 trigger: 'Call it before publishing a large or multi-file site.' That routes the agent away from blind publishing. It doesn't name explicit alternatives or when-not conditions, but for a read-only limits endpoint those are largely unnecessary.

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

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

No annotations exist, so the description carries the full burden. It does disclose the read scope and the auth requirement for protected pages, but calling it a 'password header' conflicts in phrasing with the schema's `password` request property, which can mislead an agent about how to supply credentials, and nothing is said about error behavior or return shape.

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

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

Three short sentences, front-loaded with the core action and scope, with no filler. 'Format-specific code/text' is slightly loose but does not waste space.

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

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

For a 3-parameter read tool with no output schema or annotations, the description covers what is retrieved, what is not, and the protected-read path. Remaining gaps (failure behavior on a wrong/missing password) are minor.

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 adds no information beyond the schema for `id` and `namespace`, and its 'password header' wording introduces ambiguity against the schema's `password` parameter rather than clarifying 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?

The description names a specific verb (fetch) and resource (stored rendered HTML or format-specific code/text) keyed by namespace and ID, and explicitly excludes the owner-only original-source endpoint and browser viewer. It does not, however, distinguish itself from siblings like get_json or get_kv, which also return format-specific content.

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

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

It gives explicit negative routing: this reads API content, not the original-source endpoint or the browser viewer, and states that protected reads require the password. It stops short of naming sibling alternatives (e.g., get_json) as the recommended path for other content types.

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

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

No annotations are provided, so the description carries the full burden. It does disclose useful behavioral context: the disjoint count invariant (alive_public + alive_private + deleted == total) and the tz effect on the 'today' boundary. It does not state that the operation is read-only/safe or whether results are cached/live, which for a no-annotation tool would have been worth including.

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: purpose first, then the count invariant, then the parameter nuance. Every sentence carries content; only minor redundancy with the schema on the UTC default keeps it from a 5.

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

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

For a single-optional-parameter aggregate reader with no output schema, the description gives enough: what metrics come back and how the counts partition. Missing only a statement of read-only safety and whether figures are real-time, which would round it out given zero 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% and the single `tz` parameter is fully documented there, including the silent UTC fallback. The description's mention of the 'today' boundary shift restates what the schema already says, adding no 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 and resource ('Get BrewPage platform-wide usage statistics') and enumerates the returned metrics (page count, file count, storage usage), which is clearly distinct from the publish/update/delete siblings. It stops short of naming an alternative, but the read-only aggregate nature is unambiguous.

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

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

Usage is only implied: an agent can infer this is the read-only aggregate-statistics tool versus the per-record getters (get_page, get_json, get_kv). There is no explicit statement of when to prefer it over those siblings or any exclusions, so it remains inference rather than guidance.

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

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

With no annotations, the description carries the full burden, and it does add real value: size caps (5 MiB files/audio, 20 MiB video), what gets returned (share link and owner token), and the absence of password/TTL inputs. It does not disclose auth requirements, overwrite/idempotency behavior on repeat uploads, or failure modes, leaving meaningful gaps for a mutating tool.

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

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

Four short sentences, front-loaded with the core action, then limits, then return values, then scope boundaries. No filler, though the return-value sentence is somewhat compressed compared to the afterthought phrasing of the last sentence.

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

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

No output schema exists, so the description's mention of the primary share link and owner token is necessary and present. Combined with the 100%-covered input schema, the definition covers enough to call the tool correctly, with the only gap being permission/auth expectations.

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

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

Schema description coverage is 100%, so the parameters are already well documented, and the baseline of 3 applies. The description adds the size-limit context and the explicit exclusion of password/TTL options, but nothing about how filename or namespace affect the result 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 ('Upload a file to BrewPage via URL'), which cleanly separates it from publish_site, publish_html, publish_json, and publish_kv by naming the resource type. It does not explicitly name a sibling or exclusion, so it stops short of 5.

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

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

Usage is implied by 'upload a file via URL', and the note that password/TTL inputs are not exposed signals a scope boundary. However there is no explicit 'use this instead of publish_site when...' guidance and no stated prerequisites, so the agent must infer selection from the resource noun.

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

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

With no annotations, the description carries the full burden and discloses useful behavior: returned share link and owner token, default 5 MiB limit, Markdown sanitization rules, automatic subdomain delivery behavior, and the notice fields returned when deliveryMode is auto-selected. It still omits auth/permission requirements and explicit create-vs-update semantics.

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 purpose and return values, then adds operational caveats. It is dense but each sentence contributes relevant information for an 8-parameter publishing tool.

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

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

For a complex tool with no output schema and no annotations, the description supplies return details (share link, owner token, deliveryModeReason, delivery notice), sanitization rules, size limit, and delivery-mode caveats. The main remaining gap is explicit routing guidance versus sibling publishing/update tools.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description restates high-level features (password, TTL, filename, showTopBar, deliveryMode) but adds little syntax or meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Publish HTML or Markdown content to BrewPage'. It also names the return artifacts (share link and owner token). However, it does not explicitly distinguish this tool from siblings like publish_site, publish_file, or update_html.

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

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

Usage is implied by the content type ('HTML or Markdown content'), and there is conditional guidance such as passing 'public' ONLY when gallery/search eligibility is explicitly wanted. But the description never states when to choose this tool over publish_site, publish_file, publish_json, or update_html.

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

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

With no annotations, the description carries full burden: it usefully discloses the ~1 MiB repository limit and that the call returns a share link plus owner token. It does not mention that a creation can return an existing publication, nor the visibility/indexing implications, leaving those entirely to the parameter schema.

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

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

Two compact sentences, front-loaded with the action and resource, then the payload contract, then the return value. No filler or repetition of schema 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 7-parameter mutation tool with no annotations and no output schema, the description covers the essential contract: accepted payload forms, size limit, and return values. The gaps (idempotency/duplicate behavior, visibility defaults) are addressed in the unusually detailed parameter schema, so little is missing for correct invocation.

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, but the description adds real value by saying the payload may be any valid JSON 'including scalars/null' — the schema's anyOf only lists string/object/array, so this clarifies that scalar content is acceptable (via JSON-encoded string). Other params (ttlDays, namespace, deliveryMode) are left to their rich 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?

States a specific verb and resource ('Publish a JSON document to BrewPage') and names the destination, which cleanly separates it from the sibling publish_html, publish_file, publish_kv and publish_site tools that publish other resource types. It also states the observable outcome (share link and owner token).

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 'Publish' and the accepted payload forms, but the description never says when to prefer this over siblings such as update_json/republish_site/get_json, nor when-not to use it. The reader must infer that this is for first-time publication of new JSON content.

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

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

With no annotations, the description carries the burden well: it discloses quota defaults (1 MiB per value, 1,000 keys per store), that a KV store is created, and what is returned (primary share link and owner token). It omits overwrite/duplicate-key behavior and whether a create-side-effect occurs on repeated publishes, 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 action and addressing, then limits, then return shape — every clause earns its place. Minor looseness in the "Repository defaults" phrasing, but 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?

For an 8-parameter mutation tool with no annotations and no output schema, the description supplies the return values, quotas and addressing model an agent needs. The remaining gap is whether publishing the same (namespace, id, key) creates a new store or updates an existing one, which materially affects correct invocation.

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; every parameter including ttlDays clamping and deliveryMode is already documented in the schema. The description only adds the (namespace, id, key) tuple concept and quota defaults, which are useful but not parameter-level semantics 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 ("Publish a key/value entry to BrewPage") and adds the addressing model (namespace, id, key), which is more than the name conveys. It does not differentiate against siblings such as set_kv, publish_json or publish_file, so an agent must infer which publish/set variant to pick.

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

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

The description never says when to use this instead of set_kv, publish_json or publish_file, nor any prerequisite or exclusion. The only routing-like guidance (namespace unlisted vs public) lives in the schema's namespace parameter, not in the description itself.

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

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

With no annotations, the description carries the full burden and does substantial work: discloses site/request/file limits, that system files are skipped and never counted, that unsupported extensions and long paths surface in notices, TTL rounding/clamping behavior, and a full 400/413/422 error taxonomy. It omits auth requirements and whether re-publishing overwrites or creates new, so not 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?

Dense but front-loaded: the primary single-page/multi-page split comes first, then limits, then the entry chain, then errors. Each clause carries operational information, though the error-code block is tersely packed and would benefit from lighter grouping.

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 an 8-param mutation with no annotations and no output schema, the description covers limits, skipping behavior, entry resolution, error mapping, and hints at the return contract (primary link, owner token, expiresAt). The return shape is only partially described, which is the main residual gap absent an output schema.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds genuine value beyond the schema: the entry resolution chain ('entry, else root index.html, else the shallowest HTML file') and the instruction to retain the owner token and use the returned primary link / expiresAt.

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 behavior into single-page (`entryContent`) vs multi-page (`files`) modes. However, it never distinguishes itself from the sibling `publish_html` or `publish_file`, so an agent must infer the boundary between a 'site' and a 'page'.

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 concrete selection criteria: single vs multi-page, when `entry` overrides, and entry fallback resolution. It also routes the agent to `get_limits` for current limit values. It stops short of naming sibling alternatives (publish_html/publish_file) or stating when NOT to use this tool.

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

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

With no annotations, the description carries the full load and does so well: it discloses destructive semantics ('files absent from it are removed'), the owner-token auth requirement, that republishing preserves existing expiry, and that a supplied ttlDays is ignored via a notice. Limits are enumerated and routed to get_limits, plus skip behavior for system/unsupported files.

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 destructive full-replace contract, then mode selection, then limits and error codes in a logical order. It is dense and the error-code catalogue is long, but essentially every sentence supplies actionable information rather than 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 an 8-parameter mutation tool with no annotations and no output schema, the description covers what an agent most needs: destruction semantics, auth, limits, file-skip behavior, entry resolution, and status-code mapping. Nothing material is left for the agent to guess.

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 earns above that by adding precedence semantics the schema lacks: entry resolution falls back to root index.html, then the shallowest HTML file, and ttlDays is explicitly inert. Mode pairing of `entryContent` vs `files` is reinforced rather than merely repeated.

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

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

States a specific verb and resource with scope: 'Republish (full-replace) an existing multi-file BrewPage site in place at the SAME URL/ID.' The parenthetical defines the exact semantics (full replace, same identity), which cleanly separates it from publish_site (new site) and update_html (partial edit).

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 concrete mode-selection rules: single-page uses `entryContent`, multi-page uses `files`, and `entry` overrides the default entry. The 'in place at the SAME URL/ID' framing implies this is for replacing an existing site rather than creating one, but no sibling tool is named explicitly as an alternative (e.g., publish_site, update_html).

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?

Since there are no annotations, the description bears the full burden of behavioral disclosure. It successfully explains the security implications of the 'mine' flag, stating it requires an owner token for scoping.

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 extremely concise, using two sentences to define the purpose and list all primary operational modes (filters and 'mine' mode) without any unnecessary fluff.

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

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

The description effectively complements the 100% schema coverage by explaining the functional implications of 'mine.' It is highly complete for a search utility, needing no explanation of return formats.

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?

Given the 100% schema coverage, the baseline is 3. The description adds semantic value by linking the 'mine' parameter to the security requirement of the 'owner token,' providing context the schema descriptions lack.

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

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

The description clearly identifies the action ('Search'), the resource ('BrewPage public gallery'), and differentiates it functionally from the general resource management tools listed in the sibling 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?

It identifies the nature of the inputs ('Optional filters: text query, pagination, sort') and highlights specific conditional usage for the 'mine' filter. It is clear on scope, though it lacks a specific 'use this vs get_page' comparison.

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

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

No annotations are provided, so the description carries the full burden. It does disclose an auth requirement (owner token) and that the store must pre-exist, which is real value, but it omits overwrite semantics for an existing key, failure behavior for unknown namespaces, and any response indication.

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 scoping constraint about the store needing to exist is front-loaded ahead of the auth note.

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?

Five required parameters, no output schema, and no annotations mean the description should do more. It covers purpose and prerequisites adequately but leaves overwrite behavior and return expectations unstated for a mutation tool.

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

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

Schema description coverage is 100%, so all five parameters including ownerToken and namespace are already documented in the schema. The description adds only a passing mention of the token requirement and nothing about key/value format constraints.

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 ('Set or update') plus the exact resource ('a key in an existing BrewPage KV store'). The write-oriented verb cleanly separates it from read siblings like get_kv, though it doesn't explicitly name publish_kv as the store-creation alternative.

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?

'Existing' implies the store must already exist and 'Requires owner token' implies a prerequisite credential, but neither is framed as explicit when/when-not guidance. No alternative is named for creating a store or for reading a key back.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the auth requirement, that version mismatches are reported rather than rejected, that a stale version still applies, that old links and forced subdomain modes remain unchanged, and that the result surfaces a delivery notice. The remaining gap is failure modes (invalid owner token, ineligible resource) and whether the mode change is reversible.

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 tight paragraph, front-loaded with scope and exclusions before the mutation semantics. The semicolon-chained clauses about version mismatches and unchanged links are dense but each carries real information, so nothing feels 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 tool with no annotations and no output schema, the description covers scope, auth, version-mismatch behavior, and side effects on existing links. It only lacks explicit error/failure conditions and a fuller sense of what the returned delivery notice contains.

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 every parameter is already documented, including expectedVersion's stale-value behavior and the enum meanings for type and deliveryMode. The description's "pass the current hostingVersion when known" and the type/namespace exclusions largely restate what the schema says, adding only modest emphasis rather than new semantics.

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

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

States a specific verb+resource ("Change delivery mode for a NEW publication") and immediately carves out two explicit exclusions (not a site, not a non-public HTML-format page), which is exactly what distinguishes it from sibling publishing tools like publish_site or update_html. An agent can classify the target resource before opening any schema.

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

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

Gives clear when-to-use conditions (new publication only, exclusions for sites and non-public HTML pages) and a prerequisite (owner token, pass hostingVersion when known). It stops short of naming the sibling tool an agent should use instead for the excluded cases, leaving that inference to the agent.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the auth requirement, that the link and delivery mode are immutable on update, that metadata is returned, and that a deliveryModeReason/delivery notice may be surfaced when content uses unsupported browser features. It does not state that existing content is overwritten or whether the operation is reversible, which keeps it below 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?

Front-loaded with the action and resource, followed by prerequisites and behavioral caveats in three dense sentences with no filler. The final sentence is long but each clause (immutability, advisory reason, delivery notice) carries distinct information.

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

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

For a 5-parameter mutation tool with no annotations and no output schema, the description covers the return value (updated page metadata), auth, and the immutability/advisory behavior. The main remaining gap is what happens to existing content and error conditions on a bad or stale owner token.

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 (including the format enum-ish list and the 'omit to preserve stored format' behavior) are already documented in the schema. The description adds only the ownerToken requirement, which the schema already marks as required, 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: 'Update an existing BrewPage HTML/Markdown page.' The scoping to HTML/Markdown pages implicitly separates it from update_json and update_hosting, but no sibling is named explicitly, so an agent must infer the boundary from the resource wording.

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?

'Requires owner token' gives a clear prerequisite, but there is no statement of when to use this versus publish_html (creation) or republish_site. Usage is implied by the word 'existing' and the immutability note, not stated as explicit when/when-not guidance.

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

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

Since no annotations were provided, the description carries the full burden of disclosure. It successfully calls out the necessary security prerequisite ('Requires owner token') and the technical flexibility of the payload format, which is crucial behavioral context for the agent.

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 extremely concise, front-loading the primary function first and then following with the critical constraint and input flexibility. There is zero wasted language.

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 that there are no output schemas or annotations, the description is robust enough to handle the key operational complexities: authentication requirements (owner token) and input data flexibility (various JSON formats).

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?

Although the schema covers the parameters, the description explicitly explains the functional meaning of the 'json' input: that it accepts three distinct types (object, array, or string), making the polymorphic input highly understandable to the agent.

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

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

The description clearly states the function as updating an 'existing BrewPage JSON document.' It is specific about the resource being targeted (BrewPage JSON) but does not explicitly compare itself against other JSON siblings (e.g., update_html).

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

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

Usage is implied by the tool name and description, stating it updates an existing document. However, it offers no guidance on specific scenarios where this tool should be preferred over alternatives like 'get_json' followed by a 'publish_json' sequence.

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