Pagehaus

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

Annotations already declare non-read-only, non-destructive, non-idempotent, and closed-world. The description goes beyond them by disclosing the post-condition (site is served there once records are in place), the automatic HTTPS provisioning, and the plan entitlement — real behavioral context. It stops short of stating what happens on a duplicate/conflicting domain or whether the call 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?

Three short sentences, front-loaded with the action and followed by the outcome and the plan caveat. Every sentence carries information: what it does, what you must do next, what happens after, and who is eligible. Slightly more than strictly needed but nothing is wasted.

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

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

With no output schema, the description correctly explains the return (DNS records) and the eventual outcome, plus entitlement gating. What is missing is failure/edge behavior — e.g., an already-claimed domain or a pending verification state — which an agent would want before calling.

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% for both required parameters, so the schema already documents 'site' and 'domain' formats. The description contributes only the constraint that the domain must be owner-controlled and repeats an example format already present in the schema. 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 and resource ('Adds a domain ... to a site') and immediately clarifies scope: an owner-controlled custom domain, distinct from list_domains or check_domain. The return value (DNS records to configure) is named, so the agent knows exactly what this call yields.

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 an implicit eligibility rule ('Custom domains come with the Personal and Pro plans') which is genuinely useful gating context. However, it never says when to reach for this versus the closely related check_domain sibling, nor what prerequisite state the site must be in. Usage is implied rather than directed.

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 readOnlyHint=false, and the description justifies that by explaining it actively re-queries DNS 'again now' rather than just reading cached state. It also adds timing expectations (automatic rechecks, DNS propagation lag), which goes beyond the structured hints, though it does not say what a failed or pending result looks like.

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

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

Two sentences, purpose front-loaded before the timing caveat, with no filler. The second sentence is slightly conversational but earns its place by setting expectations about automatic rechecks.

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 status-check tool with no output schema and no return-value annotation, the description stops at 'returns its status' and never enumerates possible states (pending, verified, failed) or how the agent should interpret them. Timing context is covered, but the result semantics are left implicit.

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

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

Schema description coverage is 100%, so both 'site' and 'domain' are already documented in the schema, and the description adds no syntax or format detail for them. Baseline 3 is appropriate when the schema carries the parameter burden.

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: it looks up a custom domain's public DNS now and returns its status. That is clearly distinguishable from add_custom_domain (write) and list_domains (enumerate all), though the description never names those siblings explicitly.

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

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

The note that Pagehaus re-checks newly added domains automatically every couple of minutes implicitly tells the agent a manual call is only needed for an immediate re-check, which is useful but not framed as guidance. There is no explicit when-to-use statement and no named alternative (e.g. list_domains) for checking existing state.

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, but the description adds substantial context beyond them: includes are processed before checking, forms must post to /_form/<name>, dead addresses are drawn from the last 30 days of visitor traffic, and external links are out of scope. That is exactly the kind of hidden behavior an agent needs to interpret results.

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 verb and scope are front-loaded, the checklist of failure modes follows, and the closing sentence carries both the usage trigger and the exclusion. It is dense but every clause earns its place; nothing is 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 one-parameter read-only diagnostic, the description covers scope, triggers, and exclusions thoroughly. The only minor gap is that it doesn't state what the result looks like (a list of issues vs. a pass/fail), though with no output schema that is a small omission.

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

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

There is one required parameter, `site`, and the schema already documents it at 100% coverage ("The site name."). The description's phrase "a whole Pagehaus site" adds a little framing but no syntax or naming details 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 (checks) and a precisely scoped resource (a whole Pagehaus site as visitors see it), then enumerates exactly what is examined: broken links/images, failing includes, undeliverable forms, missing index.html, and recently-hit dead addresses. This is far more specific than its sibling check_domain, which is about domains, not site 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?

"Use it after making changes" gives a clear trigger for invocation, and "Links to other websites aren't checked" draws a scope boundary. It stops short of naming check_domain or other alternatives explicitly, so it's clear context rather than full when/when-not routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered structurally. The description adds real context beyond that: the connection-scope requirement, the provisioning side effect (starter page), and the resulting public URL. It does not state what happens on a duplicate/non-idempotent repeat call, which is the one notable 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?

Three short sentences, no filler, and the core action is front-loaded ahead of naming rules and the availability constraint. Every sentence carries distinct, 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?

For a single-parameter creation tool with no output schema, the description supplies everything needed to call it correctly: the effect, the naming contract, the resulting URL, and the gating precondition. Nothing material is missing.

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

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

With 100% schema coverage the baseline is 3, but the description earns more by adding naming constraints the schema omits: lowercase letters, numbers and hyphens, 3 to 40 characters, plus the derived URL form. Those constraints directly determine whether a caller-supplied name is valid.

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

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

The description names a specific verb and resource ("Creates a new site") and adds the concrete side effect an agent needs: a starter page is provisioned and the site is live at https://<name>.pagehaus.site/. It is unmistakably distinct from siblings like list_sites or add_custom_domain.

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 states an explicit applicability precondition — "Only available when the connection covers all sites" — which tells the agent when the call will succeed. It does not name an alternative tool or a when-not-to-use case, so it stops short of the top score.

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, so the risk profile is known; the description adds that the deletion is permanent and that folders require emptiness, plus an API reference link. This is useful extra context beyond the structured fields.

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

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

Front-loads the action and scope in the first clause, then adds the path clarification and permanence warning. Slightly padded by the API URL, but no wasted 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?

For a two-parameter destructive tool with full annotation coverage and no output schema, the description covers scope, the empty-folder precondition, and irreversibility. It omits error behavior (e.g. non-existent path), a minor gap.

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

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

Schema coverage is 100%, so both parameters (site, path) are already documented in the schema. The description restates path as a file-or-folder inside the site and gives the same example, adding only marginal meaning 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 (deletes) and resource (one file, or an empty folder) scoped to a Pagehaus site, which clearly separates it from the read/write/list file siblings. An agent immediately knows what this tool does.

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

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

Provides an implicit precondition — a folder can only be deleted once it's empty — but never names an alternative (e.g. list_files to confirm contents) or states when-not to use it. Usage is implied rather than guided.

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, so the safety profile is covered; the description adds genuinely new context — the side effect of re-publishing the blog so the page disappears, and the recoverability path via the site's version history in the dashboard. It stops short of stating auth/permission requirements or whether the call is immediate and permanent outside that recovery window.

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, each carrying distinct information (what it does, the visibility side effect, the recovery route). No waste.

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

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

For a 2-parameter destructive tool with no output schema, the definition covers the essential behavioral facts: the side effect and the undo path. Only minor gaps remain (whether anything is returned, whether the caller must be the owner).

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% — both `site` and `slug` are documented with an example in the schema — so the description adds no parameter meaning and the baseline of 3 applies.

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

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

States a specific verb and resource ("Deletes a post from a Pagehaus site's blog") that clearly distinguishes it from siblings like delete_file, list_posts, and write_post. It doesn't explicitly name the near-alternatives, but the scope 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 implied by the verb and resource rather than stated: nothing says when to delete vs. unpublish via write_post, or that this is irreversible at the tool level. The conditional about public posts hints at behavior but is not framed as guidance for choosing the 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?

Annotations already flag destructiveHint=true, but the description adds the details that actually matter: irreversibility, the 30-day name reservation, exactly what data is destroyed, and a connection-scope availability limit. These are traits the agent cannot infer from the annotations alone.

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

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

Three tight sentences, front-loaded with consequences and followed by the guardrails. No filler and no repetition of the tool name or title.

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

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

A destructive, no-output-schema tool with two fully documented parameters. The description covers consequences, irreversibility, prerequisites and confirmation, which is everything needed to call it safely; return values are irrelevant for a deletion.

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

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

Schema coverage is 100% and both parameters already document themselves, including that confirm must be the exact site name. The description restates the confirm ritual ('pass its name again as confirm') without adding syntax or edge-case behavior 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?

Names a specific verb and resource and immediately enumerates the blast radius: files, version history, form messages, custom domains, visitor stats. The phrase 'a whole site' distinguishes it from siblings like delete_file and delete_post without needing to name them.

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 gate — 'Only do this when the owner has asked for this site to be deleted' — plus a precondition ('Only available when the connection covers all sites') and a confirmation ritual. It stops short of naming narrower alternatives such as delete_file for partial cleanup, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds the useful detail that results are measured in bytes against the plan, but says nothing about scope (per-site vs account) or freshness, which is a modest contribution beyond the annotations.

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

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

One tight sentence that front-loads the verb and enumerates the returned metrics with units. No filler, though it is quite terse given the tool takes a site argument.

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

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

For a simple read-only metric tool with a fully documented single parameter and no output schema, the description tells the agent what data comes back, which is the key missing piece. Only minor gaps (per-site scope, currency of data) remain.

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

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

Schema coverage is 100% and there is a single 'site' parameter already documented in the schema. The description adds no parameter-level detail, so the schema carries the load — the baseline 3 for high coverage.

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

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

States a specific verb ('Shows') and resource set (storage, files and folders, and traffic) scoped against the account's plan, with units (bytes). Clear purpose, though it does not explicitly differentiate itself from siblings like list_files or list_sites that touch overlapping resources.

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 name and content — an agent can infer this is for checking consumption against a plan — but there is no explicit when-to-use, when-not-to-use, or alternative routing. Adequate but with an obvious gap.

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 (readOnly, idempotent, non-destructive, closed-world), and the description goes beyond them by disclosing result ordering and that each entry carries the originating app or token. It does not discuss result volume or pagination beyond the limit parameter, but that is minor for a simple read.

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 sentence that leads with the operation, then scope, then examples, then ordering and attribution. No filler or repetition of the title or schema.

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

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

With no output schema, the description does the work of characterizing the return: change types, order, and per-entry actor. Combined with annotations that cover safety and a fully documented single parameter, an agent has what it needs, though 'connected apps' could be spelled out slightly more.

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 optional parameter with 100% schema description coverage ('How many changes, 1 to 100', default 30), so the schema already carries the semantics. The description adds nothing about the limit, which is the baseline 3 case rather than a gap.

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

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

States a specific verb and resource ('Lists recent changes') and pins down the scope precisely: changes made through the Pagehaus API and connected apps, with concrete examples of the change types. The ordering ('newest first') and actor attribution ('which app or token made each one') make it obvious this is a cross-resource activity feed, not a per-resource listing like list_files or list_sites.

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 examples (files written or deleted, sites created, domains added) imply the audit/history use case and implicitly distinguish it from the enumeration siblings, but no alternative is named and no when-not-to-use guidance is given. Usage must be inferred rather than read.

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 description's added value is the return content: the three possible statuses and the conditional inclusion of required DNS records until a domain goes live. That conditional behavior is genuinely useful context beyond the annotations, though permissions or pagination behavior is not mentioned.

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

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

One sentence, front-loaded with the verb and resource, with the return details folded in efficiently. The parenthetical status list makes it slightly dense but nothing is wasted.

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

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

There is no output schema, so the description must carry return-value burden — and it does, explaining statuses and the conditional DNS-record payload. For a one-parameter read tool this is sufficient 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?

With a single parameter and 100% schema description coverage, the schema already documents 'site' as the site name. The description adds no additional semantics about the parameter, 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 (Lists) and resource (a site's custom domains) and enumerates the status values it returns. It is clearly distinguishable from siblings like add_custom_domain and check_domain 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?

The purpose implies when to use it (inspecting existing domains and their DNS setup), but it never states when-not to use it or points to an alternative such as check_domain for a single domain. Usage 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=false and openWorldHint=false, so the safety profile is covered. The description adds that this goes through the Pagehaus files API (with a docs link), but says nothing about ordering, pagination, or what a returned entry looks like for a mutation-free listing 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?

Two tight sentences, with the scope statement front-loaded and the path clarification second. The inline API help URL is marginally useful but is the only bit of text that is not strictly needed to invoke the tool.

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

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

For a two-parameter read-only listing with full schema coverage and annotations covering safety, nothing essential is missing: resource, scope, and the one non-obvious parameter are all stated, and no output schema exists that would need describing.

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 are documented there, so the schema carries the load. The description restates the path semantics (folder inside the site, e.g. "/" or "/blog") but adds no formatting, normalization, or error behavior 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 (lists) and resource (files and folders in one folder of a Pagehaus site), with the scoping constraint that it covers a single folder. The resource noun naturally separates it from list_sites/list_domains/list_activity, but it never explicitly differentiates listing from read_file/write_file/delete_file, which is the sibling pair an agent could confuse.

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

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

Usage is only implied: the mention of "one folder" and the path parameter suggest browsing a directory before reading or writing a specific file. There is no explicit when-to-use, no stated exclusion, and no pointer to read_file as the next step, so the agent must infer the routing.

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 adds genuinely non-structured context: results are ordered newest first, field values are untrusted text authored by members of the public (a prompt-injection warning), and visitor IP addresses are deliberately excluded. It does not describe default/max result size or pagination behavior.

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

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

Three sentences, each load-bearing: purpose plus ordering first, then the untrusted-content warning, then the IP-exclusion note. No repetition of what the schema or annotations already say.

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

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

With no output schema, the description still tells the agent enough about the return shape (newest-first messages, untrusted text fields, no IPs) to consume results safely, and the schema supplies pagination. A brief note on default page size or how to detect the last page would close the remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents form filtering, the 1-50 limit, the site name, and the 'before' cursor. The description adds no parameter-level meaning beyond the 'newest first' ordering that contextualizes the cursor. Baseline 3 when the schema carries the full parameter burden.

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 (Lists) and resource (messages sent through a Pagehaus site's contact forms) plus ordering (newest first). This is trivially distinguishable from siblings like list_files, list_activity, and list_sites, which target entirely different resources.

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 resource description (read contact-form submissions), but there is no explicit when-to-use or when-not-to-use guidance and no named alternative among the eleven siblings. The API help URL gives provenance but not routing criteria.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds real value beyond that: newest-first ordering, returned fields per post (status and, once published, its web address), and the empty-blog edge case. Pagination/limits are not disclosed, keeping it just short of full transparency.

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 well-formed sentence front-loads the core purpose and packs in ordering, return fields, and the empty-blog edge case with zero wasted words.

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

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

For a one-parameter read-only list tool with no output schema, the description adequately explains what is returned (posts with status and published URL) and ordering. Absent pagination or result-limit behavior, it is nearly complete but not exhaustive.

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

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

Schema coverage is 100% with a single documented 'site' parameter, so the schema carries parameter semantics. The description references 'a Pagehaus site's blog' consistently but adds no syntax or format guidance beyond the schema. 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 (Lists) and resource (the posts of a Pagehaus site's blog) and adds ordering (newest first) and returned fields (status, web address). This distinguishes it from siblings like read_post (single post) and write_post (mutation), 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?

Usage is implied by the listing purpose and the note that no posts are returned when no blog exists, but there is no explicit when-to-use guidance or named alternative (e.g., read_post for a single post). The agent must infer the appropriate context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the results are scoped to what this connection is authorized to use, and each entry includes its web address. It does not mention pagination or result size, 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?

A single front-loaded sentence with no filler; the scope qualifier and the returned field are packed into one clause without redundancy.

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

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

For a zero-parameter read-only lister with annotations covering safety, the description supplies the two things an agent needs: authorization scope and the fact that web addresses are returned. With no output schema, a fuller picture of the returned record (IDs, other fields) would make it complete.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter surface for the description to clarify.

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

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

States a specific verb and resource ("Lists the Pagehaus sites") and narrows the scope to those the connection can use, which separates it from sibling listers like list_domains and list_files. It stops short of explicitly contrasting itself with those siblings, so it is clear but not fully differentiated.

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

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

The description implies the usage context (enumerate the sites available to this connection) but never states when to prefer it over siblings such as list_domains or create_site, nor any exclusions. Usage is inferable from the verb but not 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 already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds only that the return is a per-topic reference; it says nothing about output shape (markdown vs plain text, length) or that responses are static and cacheable.

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

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

One sentence, zero waste, with the resource front-loaded and the valid topics immediately after. Nothing to trim and nothing buried.

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

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

For a one-parameter read-only lookup with full schema coverage, the description is nearly sufficient. The only real gap is what the returned reference looks like, which matters slightly since there is no output schema, but the tool is simple enough that an agent can 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% and the single 'topic' parameter is documented inline with the same three values the description lists, so the description adds no meaning beyond the schema. Baseline 3 applies since the schema does all the work.

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 ('Returns Pagehaus's reference') and enumerates the three topics it covers. That is enough to distinguish it from every sibling, which are all site/file/post CRUD operations, though it never explicitly contrasts itself with them.

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 topic list implies when to call it (before working with includes, forms, or the blog), but the description never says so directly — no 'use this before X' framing and no mention of what to do for topics outside the three.

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

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

Goes beyond the annotations by describing the actual side effects: pages, feed and sitemap are regenerated, non-draft posts become public at their address, and removed or unpublished posts disappear. "Changes are public immediately" adds an important visibility caveat not in the structured fields. Not a contradiction with destructiveHint=false — this is regeneration, not data deletion — though noting that it only affects the public surface, not stored content, would complete it.

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

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

Two tight sentences, front-loaded with the verb and outcome, then the immediate-public consequence. No filler or repetition of the title.

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

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

For a one-parameter publish tool with annotations declaring non-destructive, idempotent and closed-world behavior, this covers what actually happens to the site and its public output. No output schema exists so return values needn't be explained; only a hint about ordering relative to post-writing tools is missing.

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

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

Schema coverage is 100% and the single parameter (site) is documented as "The site name." The description adds no syntax, format, or naming guidance beyond that, so it neither compensates nor detracts — 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 ("Publishes a Pagehaus site's blog") and then spells out the concrete mechanics — pages, feed and sitemap are rewritten from posts. That distinguishes it clearly from content-authoring siblings like write_post and delete_post without needing their schemas.

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

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

Usage is only implied: the description makes clear the tool materializes the post list into public output, so an agent can infer it belongs after post edits. It never states when to call it versus alternatives or whether it must follow write_post/delete_post, and offers no exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuine value beyond that by disclosing the return encoding rule (text for HTML/CSS/JS, base64 for other file types), which is not captured anywhere in the structured fields.

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

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

Three tight sentences, front-loaded with what the tool does, followed by the API reference and the return-format rule. No filler sentences and every clause carries information.

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

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

With no output schema, the description steps up by explaining the text-versus-base64 return shape, which is the key thing an agent needs to interpret results. It falls short of complete only in not covering failure modes (missing site/path) or the API reference details, but annotations carry the safety profile.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description's example path '/index.html' largely repeats the schema's own example. Baseline 3 is appropriate since the description adds no new constraint, format, or validation detail beyond the schema.

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

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

States a specific verb and resource ('Reads one file from a Pagehaus site') and scopes it to a single file, which cleanly separates it from list_files and write_file. The mention of the underlying files API adds a concrete anchor for what operation is being performed.

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: read one known file, as opposed to list_files for discovery or write_file for mutation. There is no explicit 'use this when...' statement or named alternative, and no guidance on what happens if the path does not exist.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds only that the payload includes post details and the Markdown body; it says nothing about what happens if the site or slug does not 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?

A single front-loaded sentence with zero filler; the verb and scope come first and the return contents follow. Nothing could be trimmed without losing information.

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

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

For a two-parameter read-only tool with full schema coverage, rich annotations and no output schema, the description is nearly sufficient. The only real gap is failure behavior for an unknown site or slug.

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 slug parameter even includes a concrete example ('hello-world' for /blog/hello-world/), so the schema carries the parameter burden. The description adds no parameter meaning of its own, which is the expected baseline 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 ('Reads') and a precisely scoped resource ('one post of a Pagehaus site's blog'), which implicitly contrasts with the list_posts sibling. It stops short of naming that alternative, but an agent can still tell what this returns.

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?

'Reads one post' implies single-item retrieval rather than enumeration, and the required site+slug pair implies an already-known post. However, there is no explicit 'use this instead of list_posts when…' routing statement or precondition such as needing the slug first.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, and the description is consistent with them. It adds real context beyond the annotations: the change is publicly visible immediately, overwriting replaces content, folders are created on demand, and binary payloads require base64 encoding.

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 verb and resource, then path behavior, then mutation semantics, then the encoding caveat. Nothing is redundant and the API help link is the only marginal extra.

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

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

For a mutation tool with no output schema, the description covers the essentials an agent needs: scope, overwrite behavior, immediate visibility, folder creation, and binary handling. Auth requirements, size limits, and error behavior are unstated, which is the only notable gap.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds value: it explains that path is relative to the site top with an example, that intermediate folders are created, and that encoding='base64' is required for binary files such as images.

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

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

States a specific verb and resource ('Creates or replaces one file on a Pagehaus site') plus the API being used. The 'one file' scope and path semantics clearly separate it from siblings like delete_file, read_file, and list_files.

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 makes the use case clear (write a file into a site, folders auto-created, replaces existing content) and the sibling names make alternatives self-evident. It stops short of explicitly naming when to use read_file/delete_file instead, so it lacks true exclusions.

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

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

Goes well beyond the annotations: disclose that omitted details retain their current value on replace, that a blog is auto-created at /blog/ when absent, and that posts are private drafts unless publish is true, which additionally publishes the blog. This partial-update and side-effect disclosure is exactly the context annotations cannot carry, and it is consistent with destructiveHint=true and idempotentHint=true.

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

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

Four compact sentences, front-loaded with the core create/replace behavior, then the draft/publish branch, then the pointer to pagehaus_guide. No filler or restated field docs.

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 9-parameter mutation tool with full schema coverage and annotations declaring the safety profile, the description covers the key behaviors: draft default, publish side effect, auto-blog creation, and partial update. Return values are unspecified, but no output schema exists and the shape of a saved post is reasonably inferable from siblings.

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 would be 3, but the description adds real meaning beyond field docs: the upsert-by-slug model and the rule that unspecified fields keep their prior value, which reframes every optional parameter. It does not elaborate publish/date interplay further than the schema already does.

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 (writes a blog post on a Pagehaus site in Markdown) and immediately distinguishes itself from siblings by covering both create and update semantics on a slug. An agent can separate it from list_posts, read_post, delete_post, and write_file 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?

Explains the create-vs-replace condition and the private-draft-versus-publish=true branch, which are the main decision points. It also routes the agent to pagehaus_guide with topic "blog" for background. No explicit exclusions, such as when to use write_file instead for non-post content, but the context is clear.

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