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

Annotations already declare it as a non-read-only, non-idempotent, non-destructive open-world write, but the description adds material context beyond that: each call counts against plan project limits (Pro: 5, Pro+: 20), nothing is published as a side effect, and it does not write local files. This is exactly the value-add expected when annotations exist.

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 paragraphs, front-loaded with the core action, then usage/routing, then exclusions. Every sentence carries distinct information; none is redundant with the schema or annotations.

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

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

An output schema exists, so return values need not be re-explained, and annotations cover the safety profile. The description still fills remaining gaps (quota impact, publication behavior, non-local-file scope, domain limitation), making it complete 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 description coverage is 100%, so both 'name' and 'domain' are already well documented, giving a baseline of 3. The description adds little parameter-level detail, though 'cannot set a custom domain' usefully clarifies that the schema's 'domain' is only a subdomain, not a custom domain.

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 ('Create a new, empty micropage project in the signed-in account') and even describes what is returned (the project plus a starter .page file). This clearly distinguishes it from siblings like list_projects, get_project, and save_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?

Explicitly states when to use it ('when the user wants a new site'), names the alternative to check first (list_projects) with the condition that selects it ('when the user may mean an existing site'), and lays out the follow-on workflow (write the page, call save_page, publish only on request).

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

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

Despite annotations covering destructiveness/idempotency, the description adds substantial context: no undo, confirm must be true and only after user agreement, deleting a nonexistent slug is not an error (deleted:false), a site rebuild is queued and redeploys the live build while leaving drafts intact, and it returns build_id/after_event_id. This far exceeds the annotation coverage.

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 destructive nature and the sibling alternative, then flows into confirmation, edge-case behavior, and rebuild/return details. Every sentence carries distinct, load-bearing information with no filler.

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

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

For a destructive mutation with an output schema already present, the description covers reversibility, confirmation protocol, error-free misses, and side effects (rebuild + follow-up tool). Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds genuinely new semantics beyond the schema — that confirm should only be passed after user agreement, and that a nonexistent slug yields deleted:false rather than an error. These nuance the slug and confirm parameters beyond their schema text.

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

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

Specific verb+resource ('delete a post for good, removing it from the site if it was published') with clear scope, and it explicitly names the sibling it is not (unpublish_post). An agent can distinguish it from unpublish_post without opening either schema.

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

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

Explicitly states when to use this instead of unpublish_post ('to only take it off the site use unpublish_post'), notes the CLI equivalent, and gives the precondition for confirm. Alternatives and conditions are spelled out, not implied.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds real behavioral context beyond them: per-call wait up to wait_seconds with progress notifications, possibly_stuck detection, build supersession handling, and the read-only guarantee ('never starts or cancels a deploy'). It also warns that the URL may serve a stale version for up to a minute after completion and that paths 308-redirect, which an agent cannot infer from annotations or schema.

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

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

Front-loaded with purpose, then usage, then the post-success caveat, so an agent can stop reading early. It is long for a 4-parameter tool and the enumerated event states (queued, built, uploaded, domain wiring...) overlap with output schema detail, but nearly every sentence carries actionable 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?

Given an output schema exists, the description need not restate return values, yet it still covers the polling contract, wait semantics, supersession, stuck detection, and post-deploy caching/redirect caveats. Nothing an agent needs to call and correctly interpret 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further than the schema by explaining the re-call loop for after_event_id and the consequence of omitting it (whole event history, completion judged from build status alone). It also reinforces wait_seconds defaults and the 0 = snapshot behavior, adding operational meaning beyond the field 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 ('report the progress of a publish') and enumerates exactly what it returns: build status, deploy events, done flag, live URL. An agent can distinguish it from publish_build/publish_post, which it explicitly names as predecessors rather than equivalents.

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

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

Gives explicit sequencing: call after publish_build or publish_post, pass the build and after_event_id they returned, and re-call with the returned after_event_id until done is true. It also explains the after_event_id contract (only events after it end the wait) and the waiting_for_start/rebuild case, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context: that it neither uploads nor lists files, and that returned URLs are not re-upload-safe in markup. The trailing 'Read-only.' merely repeats the annotation, but the rest earns credit.

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

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

Front-loaded with the core purpose, then usage, then exclusions — a sensible order with no filler. It is slightly longer than needed because 'Read-only' duplicates the annotation and the alternative-markup point is repeated in spirit, but nothing is wasted on noise.

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

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

An output schema exists, so return values need not be explained. For a 2-parameter read tool the description covers purpose, invocation trigger, exclusions, and the markup caveat — everything an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so both parameters are already fully documented, including the filename-must-match-list_files-output constraint and the flexible project identifier formats. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Get the URL a stored project file is served from') and immediately binds it to an input key ('by its filename, as list_files reports it'). It is clearly distinguishable from siblings like upload_asset, list_files, and get_page_source.

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 when-to-use context (user wants a link to an uploaded image; a bare filename won't work) plus an explicit when-not-to-use alternative inside .page markup (prefer the bare filename, which survives re-uploads). It also names the adjacent tools for upload/list so the agent can route correctly.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, but the description adds genuinely new context: it is local, needs no network or account, and mirrors specific micropage:// resources for hosts that cannot read resources. It also discloses a hard constraint (unlisted tags are not rendered) that the agent cannot infer from 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?

Front-loaded with the return value, then usage conditions, then the topic workflow, then the local/read-only note. Every sentence carries distinct information; nothing is padding.

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

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

No output schema exists, and the description compensates by enumerating exactly what each topic returns. Combined with the closed-vocabulary warning, the local/read-only note, and the resource-mirroring explanation, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the enum values and defaults are already documented and the baseline is 3. The description still adds selection guidance beyond the schema by prescribing a workflow order ('grammar' first, then 'examples_index' -> 'example' to copy a nearby layout), which clarifies which topic to pick in practice.

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 (return) plus an enumerated resource set: the .page grammar, full reference, posts format, agent guide, example index, or a single example file. This is clearly distinguishable from every sibling, which are project/page/post/build/asset operations rather than a documentation lookup.

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?

Explicit when-to-use: 'Call this before writing or editing .page markup (and before drafting a post), unless you already have the grammar in context.' It also prescribes a sequence ('Start with topic "grammar"; use "examples_index" then "example"') and warns against guessing because the vocabulary is closed.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description's value is in the extra behavioral detail: the source is merged from all .page files when saved and returns as one file, it does not reveal what is live, and it does not download images. These are genuinely useful, non-obvious traits; only return-format/pagination behavior is left unstated.

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

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

Three tight paragraphs, front-loaded with what is returned, then the workflow, then the explicit exclusions. Every sentence carries distinct information and nothing is wasted.

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

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

With an output schema present, return values need no explanation, and the description still covers the merge behavior, version defaulting, and the two things it deliberately does not surface. Nothing an agent needs before calling it is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly, including the accepted project identifier forms and the version build-number/id syntax. The description only adds that version can be used to restore an older build, which is marginal beyond the schema and leaves the baseline of 3.

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

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

States a specific verb and resource ('Return the raw .page markup of a micropage project's active build') and enumerates the full payload (source, stored llms.txt, uploaded filenames). It is clearly distinguishable from get_project and save_page, which it names by contrast.

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

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

Explicitly says when to call it ('Call it before editing an existing site: change the returned source and send the whole file back with save_page') and when its sibling is the right tool instead ('get_project tells you which build is deployed'). The version parameter's use case (restoring an older build) is also stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description still adds useful behavior by flagging that custom-domain status is read-only and that it will not follow an in-progress deploy. Much of the remaining text restates what the output schema already returns, so it stops short of a 5.

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

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

Three tight paragraphs are front-loaded with the payload and then move to usage and exclusions, with no filler sentences. Minor redundancy in listing three separate build fields (active/latest/live) inflates the first sentence slightly, but each clause carries information an agent needs.

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

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

For a single-parameter read tool with an output schema and rich annotations, this is complete: identifier formats, return contents, use cases, and explicit non-capabilities are all covered. Nothing an agent needs to call it correctly or interpret a failure 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% and the sole parameter's schema text already documents uuid, numeric id, micropage hostname and custom domain plus 'get valid values from list_projects'. The description repeats these accepted forms but adds no new syntax, defaults, or constraints, so the baseline 3 for schema-documented parameters 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 (show one micropage project in detail) and enumerates the concrete payload: live URL, editor URL, active/latest/live build, failure reason, and read-only custom-domain status. It is immediately distinguishable from siblings like get_page_source and get_deploy_status because it names them as the wrong tool for those needs.

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 three concrete scenarios (check live vs drafted before publishing, explain a failed build, answer 'is my custom domain working?') plus explicit exclusions routing to get_page_source and get_deploy_status. It also notes the mutating action (changing the custom domain) must happen in the editor, so an agent knows when this tool is and is not the right call.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description confirms 'Read-only'. It goes further by explaining the build lifecycle — each save_page that cannot overwrite a draft adds a build while publishing reuses it — which is real context not present in annotations or schema. It stops short of describing pagination or ordering guarantees beyond 'newest first'.

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 paragraphs: what it returns, when to use it plus lifecycle semantics, then explicit navigation to alternatives. Front-loaded with the verb and resource, no filler sentences.

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

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

Output schema exists so return-format explanation is optional, yet the field list is still summarized. Combined with usage routing, lifecycle context, and full schema coverage, an agent has everything needed to select and invoke this tool.

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

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

Schema description coverage is 100% and both parameters (limit, project) are fully documented in the schema itself, including accepted project identifier forms and the default/max for limit. The description adds no parameter-level 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 and resource ('List a micropage project's builds') and immediately enumerates the returned fields (number, id, status values, timestamps, failure reason, active flag), which distinguishes it from sibling list tools like list_projects and get_deploy_status.

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

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

Gives three concrete use cases (find a build to roll back to with publish_build, diagnose a failed publish, check whether a publish is still running) and explicitly routes elsewhere when appropriate: get_page_source for a build's source, get_project for what is live now.

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 full safety profile (read-only, idempotent, non-destructive), so the trailer 'Read-only' is somewhat redundant. However, the description adds genuinely useful behavioral context beyond the annotations: the ordering (newest first), the metadata fields returned, storage accounting versus the plan limit, and what is NOT returned (no file URLs, no uploads).

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 primary purpose and returned fields are front-loaded, followed by use cases and then explicit exclusions. Three short paragraphs, each sentence carrying information, 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?

With an output schema present, return values need not be explained, yet the description still summarizes them. Combined with annotations covering safety and the schema covering the parameter, an agent has everything needed to call this correctly.

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

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

There is a single `project` parameter at 100% schema description coverage, so the schema already documents the accepted identifier forms and points to list_projects. The description adds no parameter-level detail beyond restating the project context, matching the baseline 3 when schema does the heavy lifting.

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

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

The description states a specific verb and resource — listing files in a micropage project — plus the scope (newest first) and the returned fields. It explicitly distinguishes itself from siblings like get_file_url and upload_asset, so an agent can identify it without opening the schema.

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

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

It gives three concrete when-to-use cases (finding referencable filenames for .page markup, checking whether an image is uploaded, checking remaining storage) and names explicit alternatives for the excluded behaviors (get_file_url for one URL, upload_asset for uploading). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds genuinely new behavior: only registered forms appear (registered at markup save), spam is excluded from counts, and nothing visitor-typed is ever returned. The closing "Read-only" merely restates the annotation, keeping this just short of a 5.

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

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

Three tight paragraphs, front-loaded with the resource and returned fields, then usage, then the count-only caveat. Every sentence carries information, though the trailing "Read-only." duplicates the annotation and is minor 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?

An output schema exists, yet the description still usefully summarizes what comes back (counts, not visitor content) and warns about spam exclusion and the registration prerequisite. For a one-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single `project` parameter is fully documented in the schema, including accepted formats and the pointer to list_projects. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (list the forms on a project's site) and enumerates the exact fields returned: uuid, name, page, footer-form flag, and non-spam submission counts. It explicitly distinguishes itself from list_submissions, so an agent can separate it from its siblings without reading 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 three concrete triggering scenarios (answering "how many signups/messages did my site get?", finding a form's uuid/name before reading submissions, verifying a markup-added form registered after save_page) and names the alternative tool (list_submissions) with the requirement that the user enable 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/idempotent/non-destructive, so the description's "Read-only" is partly redundant. However, it adds real behavioral context: the default sort (newest first), the exact fields returned in list vs. full mode, and the critical warning that upsert_post overwrites all fields.

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

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

Front-loaded with the core duality in the first sentence, then conditional return details, then the workflow warning. Dense but each sentence carries information, though the second sentence enumerating returned fields is somewhat heavy.

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?

Despite an output schema existing, the description is complete: an agent knows the two modes, the default ordering, the returned fields, and the prerequisite workflow before editing. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both `slug` and `project` thoroughly. The description's explanation of the slug toggle (list vs. full read) largely restates the schema, adding only the workflow note about passing the revision back.

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 dual purpose: list a project's posts (blog posts and newsletter emails) or read one in full, tied directly to presence/absence of `slug`. It clearly distinguishes itself from siblings like upsert_post, preview_post_send, and delete_post.

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 provides explicit when-to-use guidance: call with a slug before editing, because upsert_post replaces every field and you must pass the current revision back. It also names the alternative for a related need (preview_post_send for who receives an email).

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

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

Annotations already cover the safety profile, but the description adds genuinely new context: the active build may be a draft newer than what is live, and the tool is unavailable to deploy tokens. It stops short of describing pagination or account-scale behavior, which keeps it from a 5.

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

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

Front-loaded with purpose, then usage, then caveats, with no filler. The long enumeration of returned fields is partly redundant given an output schema exists, which is the only mild inefficiency.

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

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

For a zero-parameter read tool with an output schema and rich annotations, nothing an agent needs is missing: it knows what comes back, when to call it, when to prefer get_project, and the auth limitation.

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 there is nothing for the description to disambiguate; the baseline of 4 applies. The note that 'uuid, id or domain all work' is useful cross-tool semantics even though it is not a formal parameter here.

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

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

States a specific verb+resource ('List every micropage project') and enumerates exactly what comes back, which lets an agent distinguish it from get_project and list_builds without opening a schema.

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

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

Explicitly names two use cases (resolving a `project` value for other tools; identifying a project from a user-supplied site name) and routes the agent elsewhere when it needs deploy truth: 'call get_project for what is actually deployed, failure reasons and custom-domain status.'

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds substantial behavioral detail beyond them: token lifetime (15 minutes, invalidated on restart or any edit via upsert_post/list change), re-send detection logic (already-published or emailed-then-unpublished re-emails the whole list), and the MICROPAGE_MCP_ALLOW_SEND gate. This is meaningful context an agent needs before calling publish_post, though return-value specifics are left to the output schema.

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

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

Front-loaded with the core purpose and the token, then a dense but useful second paragraph on token semantics. Each sentence earns its place, though the run-on sentence about re-send detection is slightly heavy and could be tightened.

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 preview tool with an output schema, the description covers the decision-relevant facts: what the preview reports, the token's lifecycle and invalidation triggers, and the send-permission gate. Nothing an agent needs to call it correctly or interpret the result is missing.

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

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

Schema coverage is 100%, so both parameters (project, slug) are already fully documented in the schema, including accepted formats and the normalisation behaviour. The description adds nothing param-specific, so the baseline of 3 applies.

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

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

States a specific verb ('Show what publish_post would do') and resource (one post), plus the concrete artifact it returns (confirmation_token). It distinguishes itself cleanly from the sibling publish_post by framing itself as the preview/token-acquisition step rather than the action itself.

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 directive: 'Call it before every publish and show the user the result.' It also implies the relationship to publish_post (which requires the token), so the agent knows exactly when this tool applies versus the sibling that performs the send.

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

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

Annotations cover the safety profile (destructive, non-idempotent, open-world), and the description adds substantial behavioral context beyond them: the operation is refused while another build is publishing, it returns immediately with status/after_event_id/ETA, queue time is about 3 minutes unless Pro+, and naming an older build makes it the active build. This is exactly the kind of beyond-schema disclosure that helps an agent sequence calls correctly.

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 most consequential fact, that this changes what visitors see, is front-loaded in the first sentence. Subsequent sentences are dense with operational facts (confirmation, build targeting, refusal condition, async return, next call, save_page dependency) and none are 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?

Even though an output schema exists, the description pre-announces the async contract (status publishing, after_event_id, ETA) and the follow-up tool, which is essential for correct orchestration. Prerequisites, authorization/confirmation, and failure mode are all covered, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: build defaults to the active build (the one save_page just wrote), accepts an id or older build number to roll back and re-activate, and confirm must be true. It complements rather than merely repeats 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 ('Deploy a micropage build to the project's public URL') plus the consequence ('changes what visitors see'), which immediately distinguishes it from siblings like save_page or preview_post_send. The rollback capability is also named, so an agent knows the full scope of the operation.

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 gates invocation ('only call it when the user explicitly asks to publish, and pass confirm: true') and names prerequisites and follow-ups: call save_page first because it does not save source, then call get_deploy_status with the returned build and after_event_id. The refusal condition (another build still publishing) is also 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?

Annotations declare destructiveHint=true and idempotentHint=false, and the description substantiates why: re-publishing or re-publishing an unpublished post re-blasts email to the entire list. It also discloses the env-var gate with no web-only override, that stale tokens are refused with nothing changed, and the returned build_id/after_event_id handles. This is well beyond what annotations convey.

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

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

The core action and its email blast are front-loaded, then preconditions, gates, and return values follow. It is long (~200 words) but nearly every sentence carries a distinct constraint; only mild redundancy in restating the token requirement from the schema 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?

Covers preconditions, the non-idempotent re-send behavior, the environment gate with its override workaround, draft-handling during the rebuild, and follow-up via get_deploy_status. With an output schema present and detailed param descriptions, nothing material is missing for a destructive, email-sending 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 three parameters are already documented, including the confirmation_token provenance. The description reinforces the token's freshness requirement but adds little syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Publish a post: put it live on the site under /content') plus the consequential side effect (email to every active subscriber). It distinguishes itself from unpublish_post and maps to the CLI equivalent, so an agent can place it immediately among its siblings.

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

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

Explicitly states the precondition chain: get confirmation_token from preview_post_send after the last change, show the preview, get user go-ahead. It also names the refusal conditions (stale/missing token, MICROPAGE_MCP_ALLOW_SEND unset), the workaround to publish web-only (save with email: false), and the inverse tool unpublish_post.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes further by specifying what is destroyed (an active draft or failed build is overwritten, otherwise a new draft is created and made active), that drafts have no public URL, that the source is replaced not patched, and that saving registers forms. This is concrete mutation semantics beyond the annotation flags, with no contradiction.

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

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

Front-loaded with the core action and the publish boundary, then prerequisites, then return/merge details. It is longer than most definitions but nearly every sentence carries a distinct fact; minor redundancy exists because the landing.page-first merge rule appears in both the description and the pages schema.

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

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

Even though an output schema exists, the description summarizes the return (build id and number, compiler issues, editor URL) to support the downstream publish workflow, and it covers prerequisites, overwrite behavior, and side effects. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already carries merge order and replacement semantics. The description adds usable guidance the schema does not: the inline `img: <- filename` asset reference pattern, the requirement to pass every file each time, and that forms are registered as a side effect of the pages payload.

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?

Opens with a specific verb+resource ('Compile .page markup and save it as the project's draft build') and immediately draws the boundary against the sibling that publishes it (publish_build). An agent can distinguish save_page from publish_build, upsert_post, and upload_asset 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?

Explicit routing: call publish_build only when the user asks, call upload_asset first for images, call get_markup_reference when unsure of markup. It also states when NOT to expect a live result ('Post changes rebuild the live site, not this draft'), which is exactly the discrimination an agent needs.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes further and discloses what is and isn't destroyed (post kept, republishable), that sent emails are not recalled, that a site rebuild is queued when the project is published, and that drafts from save_page stay drafts. That is meaningful side-effect disclosure beyond the annotation flags.

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 effect and the permanence distinction, and every sentence carries information. It is somewhat dense and the CLI equivalence line is marginal, but nothing is padding.

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

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

For a destructive mutation with a rebuild side effect, it covers reversibility, retained data, the confirm gate, and names build_id/after_event_id plus get_deploy_status for follow-up. With an output schema present, no return-value explanation is owed, so nothing an agent needs is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds value by clarifying that confirm=true must only be passed after user agreement, which is a behavioral constraint the schema states only tersely.

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

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

States a specific verb and resource plus the observable effect: the page 404s and the post returns to draft. It also distinguishes itself from delete_post by noting the post is kept and can be republished, so an agent can separate it from siblings without opening a schema.

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

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

Gives explicit routing: use this to unpublish, use delete_post to remove for good, and publish_post is the inverse. It also states the confirm precondition and when it can be passed, which is exactly the when/when-not guidance an agent needs.

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

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

The annotations already declare destructiveHint/idempotentHint/openWorldHint, yet the description adds substantial non-annotation context: dedup/no-op on identical content, that overwriting a name deletes the old file, that already-live pages keep pointing at the old file until save_page + publish_build re-run, and that it fails against the plan's storage limit. This exceeds the annotation bar.

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 what it does and formats/sources, then ordered constraints (use-before-save, dedup, overwrite semantics, exclusions, failure mode). The four paragraphs are dense but every sentence carries an actionable fact.

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

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

An output schema exists, so return values need not be described, yet the description still orients the agent with the ordering constraint, overwrite consequence, dedup semantics, and failure mode. For a 3-param mutation with rich annotations, nothing necessary for correct invocation is missing.

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

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

Schema description coverage is 100%, including the source union variants, the 20 s URL timeout, and the path being local-stdio-only, so the schema already carries parameter meaning. The description largely restates the source options and the filename/markup relationship that the schema also documents, adding little new per-parameter detail. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Upload one image ... to a micropage project's file storage') and enumerates accepted formats, size cap, and the three accepted sources. An agent can distinguish it from list_files, get_file_url, and save_page 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?

Explicit when-to-use ('Use it BEFORE save_page or upsert_post reference the image') plus explicit when-not-to ('Do not use it for non-image files, ... images already hosted elsewhere that markup can reference by full https URL, or to look up existing files (use list_files)'). It names the alternative sibling for the lookup case.

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

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

Annotations only flag destructive/idempotent/openWorld; the description adds far more: full-replace semantics (omitted optional fields are cleared), the date exception, REVISION_CONFLICT behavior with nothing written, that live published posts change immediately and rebuild the site, that email is never sent on save, and the 'unchanged' no-op path.

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

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

Long, but the length is earned by genuinely complex behavior (replace semantics, revisions, live rebuilds, no-op detection) and the purpose is front-loaded. A few clauses (site rebuild redeploy details) could be tightened, but nothing is filler.

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

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

Covers prerequisites, conflict handling, confirmation gating, image handling, and follow-up tools (get_deploy_status), and the output schema carries the return shape. For a 14-parameter mutation tool this is essentially complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-field meaning beyond the schema: slug determines which post, revision enforces optimistic concurrency, confirm_live_update is gated on already-published state, and the date-omitted exception is called out. It doesn't restate every field, which is fine given 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 ('Create or update one post'), names the two artifact types (blog post under /content and/or newsletter email), and explains the slug keying that determines create-vs-update. This clearly distinguishes it from siblings like save_page, publish_post, and delete_post.

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 routes the agent: read with list_posts(slug) first and pass back the revision; upload images with upload_asset then get_file_url; publish afterwards via preview_post_send then publish_post. It also states when confirm_live_update is required and when nothing is written.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes further by disclosing failure semantics ('never fails for a missing login: it returns logged_in false and a note saying what the user must do'), plus an explicit non-effect statement ('does not log in, log out, or change anything'). That is behavioral context beyond what the annotations provide.

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?

Well front-loaded: what it reports, then when to call it, then when not to. Three short paragraphs with no wasted filler, though enumerating the returned fields is mildly redundant against the existing output schema.

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

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

For a zero-parameter, read-only diagnostic tool with an output schema already documenting return values, the description supplies the missing pieces: trigger conditions, failure behavior, and explicit non-mutation. Nothing an agent needs to call it correctly is absent.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing schema-side to compensate for. The description accurately implies a no-argument call and instead frames the returned identity fields, which is the relevant semantic content for a parameterless tool.

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

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

States a specific verb ('Report') and resource ('which micropage account this server acts as') and enumerates exactly what is reported: email, plan tier, subscription, and session vs. deploy-token identity. An agent can distinguish this from any sibling project/page/post tool without opening a schema.

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

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

Gives explicit trigger conditions ('first when a micropage tool fails with a login, session or plan error, or when the user asks which account is connected') and an explicit negative case ('Do not call it before every task; the other tools report login and plan problems themselves'). This is textbook when-to-use / when-not-to-use guidance.

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