Postclick by PPC.io: Landing Page CRO

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), but the description adds non-obvious behavioral context: the call is 'Free,' costs nothing, is safe to repeat, and calling it twice in a row is normal. It also discloses the response is written to be read aloud and should be relayed verbatim. It stops short of describing latency or output format details.

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

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

Purpose and routing are front-loaded in the first two sentences, and each topic clause does real selection work the enum text does not. It is nonetheless very long and dense; the topic list could be tightened without losing routing value.

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 lookup tool with no output schema, the description covers what is needed: the prerequisite, the meaning of every topic value, the shape of the return value ('written to be read out'), and how to relay it. Nothing required 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 coverage is only 50% (audit_id is undocumented), but the description compensates heavily by defining what each of the eight enum values returns — e.g. 'buyers' for who is on the page and their objections, 'leaks' for ranked problems with evidence. This is meaning well beyond the schema's bare enum listing.

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 — 'answers one question from a completed audit by returning that part of it in full' — and explicitly contrasts the scope against the sibling that returns the whole report ('unlike the entire report'). An agent can distinguish this from get_audit and get_audit_report without opening any schema.

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

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

Explicitly routes usage: 'THIS IS THE TOOL FOR ANY FOLLOW-UP QUESTION about a page you have already audited' plus a hard exclusion, 'Never answer a question about an audited page from your own summary of it.' It also states the prerequisite ('Needs a completed audit') and notes that repeated/batched calls are expected, leaving little 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the mutation/world-touching profile is covered. The description adds the non-obvious behavioural facts: it is a paid operation gated on check_balance authorisation, and it returns an audit_id that must be polled and then handed to run_cro_skill. It does not state what the destructive side effect actually consumes or whether re-running duplicates work, which keeps it off 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?

The workflow is front-loaded (authorise price, check for prior work, then invoke), and every sentence carries a distinct operational instruction or boundary. No filler or restated name/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 two-parameter, no-output-schema tool, the description supplies the missing pieces an agent needs: the pricing prerequisite, the prior-audit search branch, the returned audit_id, and the two downstream calls. Nothing required to invoke and correctly sequence it 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?

Schema description coverage is 100%, so the schema already fully documents url and context, including the 500-character limit and the 'leave it out if they have not said' guidance. The description's 'Pass campaign context already supplied' only echoes the schema's intent rather than adding format or syntax detail, so the baseline 3 is correct.

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

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

States a specific verb and resource ('Start a new landing-page audit') and explicitly excludes adjacent work ('Does not design or build a page'), which routes the agent away from build_page. An agent can distinguish it from get_audit, run_cro_skill, and build_page without opening any schema.

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

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

Gives an explicit ordered workflow: authorise price via check_balance first, search for existing work when the request concerns a prior audit, then call this tool. It also names the follow-on tools (get_audit with wait:25, then run_cro_skill) rather than leaving the agent to infer them, and supplies an exclusion condition.

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

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

Adds context beyond the annotations (destructive/openWorld/non-idempotent) by disclosing the quote-approval prerequisite, the returned build_run_id, the polling pattern via get_build wait:25, and the completion condition artifact_ready. This is exactly the operationally necessary context for a mutating build step.

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

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

Three tight sentences: purpose, follow-up polling contract, and safety constraint. No filler, and the most important information (what it builds and what it returns) is front-loaded.

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, yet the description supplies the return value (build_run_id) and the completion signal (artifact_ready) that an agent needs to proceed. Combined with the destructive annotation and the pub/share exclusion, nothing essential is missing for a 3-param build 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?

At 67% schema coverage, concept_id and direction are already documented in the schema, but audit_id has no description in either place, and the tool description adds no parameter guidance at all. Baseline 3 is appropriate since the schema carries most of the load.

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: 'Build the design the user selected into a complete HTML page.' It also names the precondition (approval of the live quote) and the return value (build_run_id), which distinguishes it from siblings like generate_concepts or publish_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?

Explicit when-to-use (after quote approval), explicit routing to the follow-up tool (get_build with wait:25), and an explicit exclusion ('Do not publish or share the page without the user asking') that separates it from publish_page/share_page.

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, so safety is covered by structured data. The description adds real behavioral value beyond that: prices are live, and the agent must "quote only returned prices; a missing price is unknown" — a reporting constraint that prevents hallucinated costs.

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 what is read, then when to call it, then the reporting constraint. Every sentence earns its place with zero 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?

There is no output schema, so the description compensates by enumerating the returned fields (balance, billing mode, audit/build/pack prices) and specifying the missing-price fallback. Nothing an agent needs to call or interpret this tool 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 there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a parameterless read and adds no misleading call-shape hints.

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 (read) and the exact resources returned: account balance, billing mode, and live audit/build/pack prices. No sibling tool (ask_audit, build_page, get_build, etc.) covers billing state, so it is trivially distinguishable.

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 before a new paid step or when the user asks about cost" gives two concrete trigger conditions that an agent can act on. It does not name a competing alternative or an explicit when-not, but no sibling overlaps this function, so the guidance is effectively complete.

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 without the description. The description adds only the minor behavioral note that no overview is needed before a page fix; it says nothing about return format or scope of the listing.

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, purpose front-loaded and the routing hint second. No wasted text, though the phrasing 'see their work' is a little colloquial for a listing 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?

With no parameters and no output schema, the description carries the full burden of explaining what the agent will get back, and it never says what 'what is in the account' actually contains. It covers the when-to-call question but leaves the return-value expectation unstated.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and baseline 4 applies. No parameter guidance is needed or expected.

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 clear verb and resource ('List what is in the account') and the title clarifies this is the Postclick account overview. It distinguishes itself from the page-fix workflow by routing those cases to run_cro_skill, though it remains vague about exactly what account contents are enumerated.

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

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

Gives an explicit trigger ('when the user asks to see their work') and an explicit when-not, naming an alternative tool ('call run_cro_skill directly; no account overview is needed first'). It does not address other plausible siblings like get_audit or search, but the primary confusable case is handled.

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 readOnly/idempotent annotations: it declares the tool is free, that Postclick does not host pages, that it returns a download link plus an implementation_prompt, and that every variant stops at a draft and never publishes without user confirmation. That last constraint is critical behavioral context an agent cannot infer.

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

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

Front-loaded with purpose and output format, and most sentences carry real routing or behavioral weight. It runs long and the 'Free.' fragment plus the hosting aside could be tightened, but nothing is filler at the level of a wasted sentence.

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

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

No output schema exists, so the description carries the return contract itself — zip contents, download link, and implementation_prompt — and it does so fully. Combined with the draft-only safety guarantee, an agent has everything needed to call and act on 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 coverage is only 50% (build_run_id is undocumented everywhere), but the description compensates for platform by explaining why it matters ('the steps for WordPress and for Webflow are genuinely different') and how to behave when unknown ('Ask if you do not know'), which adds meaning beyond the enum description. build_run_id remains unexplained in both.

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 (packages a finished page) and names the exact artifact produced (a zip with index.html, assets/, README, metadata.json). It explicitly distinguishes itself from the sibling share_page, so an agent can route 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?

Gives explicit when-to-use routing ('This is the one for a user who wants the files. share_page is the one for a user who wants something to look at'), guidance on passing platform ('Pass platform when you know where the site lives... Ask if you do not know'), and the fallback when the agent lacks site access.

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 establish read-only, idempotent, non-destructive, closed-world behavior. The description adds important output behavior: expand=* returns everything attached, long write-ups are withheld because they would exceed 100,000 characters, and each withheld item comes with its own address for later fetching.

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 opening is front-loaded and useful, but the description contains a redundant pair of sentences about get_audit_report: 'For the audit as finished prose...' and 'For the audit written up as prose instead...' say essentially the same thing. That repetition costs clarity in an otherwise informative description.

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

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

There is no output schema, but the description compensates by explaining the return shape: attached items arrive with headline detail, long write-ups are withheld with fetch addresses, and available_links allows deeper exploration. For a four-parameter retrieval tool with complex expansion behavior, this is sufficiently 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 schema already documents all four parameters. The description still adds useful semantics: uri format, bare id fallback, expand usage including `*`, and the practical reason to expand before fetching individual items.

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 read/fetch operation over a single addressed resource, with concrete address examples like postclick://audit/<id>. It explicitly distinguishes this tool from get_audit_report and get_asset, so an agent can identify when this is the right retrieval primitive.

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 guidance to use expand first, then fetch only the two or three items that matter. It also routes finished audit prose to get_audit_report and pictures to get_asset, naming the alternative tools and conditions.

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, openWorld, non-idempotent), but the description adds real context beyond them: it needs explicit user authorisation and a quote, it returns an async run resumable via get_concepts, and it must not trigger a build without user choice. It does not explain irreversibility or cost mechanics beyond the authorisation gate.

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 dense sentences front-load the purpose, then prerequisites/alternatives, then the return and next-step constraint. Every sentence earns its place, though the second and third are tightly packed with multiple instructions.

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 fills the gap by describing the return value ('a run to resume with get_concepts') and the follow-up display step. Combined with annotations covering the mutation profile, an agent has enough to invoke it correctly, though the cost/quote mechanics remain partly implied.

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

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

Schema coverage is 67%, and the schema's own descriptions already carry the meaningful parameter detail (count caps, default pack, reuse/cost behaviour, direction steer). The description adds no parameter-level semantics of its own, so the baseline of 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 — 'Generate visual design directions for an existing audit' — which is clearly distinct from retrieval siblings like get_concepts and from build_page. It names sibling tools only in supportive/workflow roles rather than stating an explicit contrast, so differentiation is clear but not maximally sharp.

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 on the user requesting designs and authorising the pack quote, routes cost checks to check_balance, and points to get_concepts for resuming the run. It even states a hard precondition ('Never start a build without their choice'), 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 only cover the safety profile (readOnly, idempotent, non-destructive); the description adds substantial context beyond that: the call is free, the url form is public with no login, the bytes form is downscaled to ~1024 across, and full-size fetches would cost several hundred thousand tokens. The embedding syntax data:<mime>;base64,<bytes> is also disclosed.

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 decision that matters most (url vs bytes) is front-loaded and the cost/context warnings are tight and purposeful. It is slightly long and repeats the `as` semantics already in the schema, but no sentence is filler for a tool with this much footgun potential.

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 present, the description carries the burden of describing returns and does so precisely: a public link for url mode, a base64 payload for bytes mode, with sizing behavior. An agent has everything needed to call it correctly and to use the result.

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: it marks `url` as the DEFAULT AND USUALLY RIGHT, warns that the choice is expensive to get wrong, and explains why max_width defaults to 1024. It duplicates rather than contradicts the schema's enum documentation, adding rationale the schema lacks.

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+resource (retrieve a stored picture by asset_id) and clarifies that designs, page captures and logos all carry an asset_id. It is unambiguous about what comes back (a link or the image bytes), but it never names or contrasts against siblings such as fetch or export_page, so it falls short of full sibling differentiation.

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 explicitly routes between the two modes: `as: "url"` is the default and correct choice for anything published with publish_page or shown to someone, while `as: "bytes"` is reserved for documents that cannot load external images (artifacts). Both the when and the when-not are stated, plus a caution that asking for bytes by habit is wrong.

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 and idempotentHint, so safety is covered. The description adds genuinely non-obvious behavior: polling with wait:25 for client compatibility, that a timeout preserves the run and is resumable by ID, and that reading does not authorize a redesign. It doesn't cover the return shape, but annotations plus these constraints carry most of the burden.

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 payload, then the polling rule, then the completion handoff. Four sentences, each carrying a distinct rule. The final clause ('reading does not authorise a redesign') is terse but earns its place as a scope constraint.

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, yet the description names the returned contents enough for an agent to use the result. Covers polling, resumption, terminal-state distinction, and downstream routing. Missing only an explicit statement of what an incomplete run returns.

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 50%, so the description must compensate somewhat. It reinforces the wait:25 polling convention and the resume-by-ID semantics, which are the operative meanings of the wait param beyond the schema text. audit_id itself is undocumented in both places but is self-evident.

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 (read audit status) and enumerates the actual payload: progress, elapsed time, ranked findings with typed edits. This distinguishes it from siblings like get_audit_report (finished report) and ask_audit (interrogating evidence).

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

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

Gives explicit when (use wait:25 while running), an explicit when-not ('a failed, cancelled or stalled run is not a finished report'), and routes to named alternatives (run_cro_skill, ask_audit) once complete. 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 cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds valuable caveats: the output can be long, missing/withheld sections remain unknown, and buyer journeys are modelled rather than customer research.

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 sentences, front-loaded with the core action and followed by practical routing and caveats. Every sentence earns its place and there is no redundant or vague language.

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

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

The description covers purpose, alternatives, output format, length expectations, and important data caveats. It is nearly complete, but the audit_id parameter remains unexplained and there is no output schema to clarify return structure further.

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 50%: topic is well documented in the schema, but audit_id has no description. The description mentions topic only in passing and does not explain audit_id's source, format, or expected value, so it adds little 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 (Read), resource (complete stored audit), and format (markdown), making the tool's function immediately clear. It also distinguishes itself from ask_audit and run_cro_skill by naming those alternatives for narrower 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?

Explicitly routes the agent: use this tool for a full review, use topic or ask_audit for one question, and use run_cro_skill for a specific deliverable. The when-to-use and when-not-to-use guidance is concrete and actionable.

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 readOnly/idempotent annotations: build duration of 15-25 minutes, that running is non-terminal and contains no page, that HTML is summarised by default to avoid flooding context, and that elapsed_seconds is server-measured build age. This is exactly the operational context an agent needs for long-poll 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?

Front-loaded with the core contract and free of padding in the opening lines, but the middle digression about a twenty-minute build becoming a handful of calls is restated at some length. Dense but slightly over-explained.

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

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

No output schema exists, so the description carries the return contract itself — status stages, non-terminal running, summarized vs. full HTML, and elapsed_seconds — and it does so completely for a 3-parameter polling 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?

With only 67% schema coverage, the description compensates: it explains the rationale for wait=300 (blocks until a material change, collapsing repeated reads) and the purpose of include_html (full page is tens of thousands of characters). It also explains the otherwise-undocumented elapsed_seconds return field.

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

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

States a specific verb and resource: returns a build's status and, once finished, the complete page. It is clearly the polling counterpart to siblings like build_page, though it never names that sibling to draw the contrast 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?

Explicit when-to-use and how: poll with wait=300, use include_html only when the user actually wants the file (e.g. to save locally), and stop and re-poll silently when the stage is unchanged. It even covers the failure mode of idempotent resumption by ID instead of restarting.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior, but the description adds substantial context: free access, 3–8 minute packs, long-poll wait semantics, non-terminal partial results, recommended flags, image return format, and placeholder content. It does not contradict 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?

The description is front-loaded with purpose and organized around polling behavior, output format, and alternatives. It is somewhat long and contains advisory repetition, but most sentences carry useful operational information.

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

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

With no output schema and rich annotations already covering safety, the description still explains return format, wait behavior, partial non-terminal states, recommended flags, placeholder content, and the share_page alternative. It is complete enough for an agent to call and interpret this tool correctly.

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

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

Schema coverage is 67%, and the description adds meaningful operational semantics for wait and concept_id beyond the schema, including wait=300 for active runs and the full-page behavior when concept_id is supplied. audit_id is only implied by context, not explicitly described, so it is strong but not complete.

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

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

States a specific verb and resource: returns every concept rendered for an audit, with image URLs, a full-size link, and a runs.active count. It also distinguishes the send-a-design case from share_page and the build case via concept_id, so an agent can route correctly.

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 operational guidance: call with wait 300 while runs.active is above zero, avoid repeating stages, treat partial sets as non-terminal, and use share_page when the user wants to send a design. The when-to-use and when-not-to-use conditions are clearly 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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds that the tool is 'Free' and that omitting the address returns every note in the workspace. These are useful behavioral details beyond the annotations, though it does not cover return format or pagination.

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

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

The description is three short, front-loaded sentences with no wasted words. 'Free' leads, then the core behavior, then a practical usage tip. Every sentence earns its place.

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

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

For a simple read tool with one optional parameter and rich annotations, the description covers what it does, when to call it, its cost, and its default scope. It could be more complete by hinting at the return format, since no output schema exists, but otherwise it is sufficient.

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 single optional parameter is fully documented. The description reiterates that leaving out the address returns all notes, which adds little beyond the schema. Baseline 3 is appropriate when the schema already 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 (returns) and resource (notes), and clarifies the scope: notes for one record or all notes in the workspace when no address is given. It does not explicitly name or contrast with any sibling tool (e.g., save_note), so it falls short of the 5-level sibling differentiation.

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 a clear usage scenario: 'Worth calling at the start of a repeat job, so a monthly report picks up whatever the last one left behind.' This is helpful context, but it does not name alternatives or state when not to use the tool, missing the explicit exclusions required for a 5.

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. The description adds valuable behavioral context by stating that it returns starter requests and portable skill downloads, and that no account or credits are needed, which goes beyond the safety annotations.

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

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

The description is front-loaded with the core purpose, then states the return contents, and closes with a useful constraint. Every sentence earns its place and there is no wasted text.

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 input parameters and no output schema, the description adequately explains what the tool returns and any account/credit constraints. It could be slightly more explicit about the listing nature or any pagination, but it is complete enough for this simple 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?

The tool has zero parameters, so the baseline score is 4 per the rubric. There is no parameter information needed or missing.

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 clear verb-resource intent: finding Postclick methods/skills for specific CRO topics and returning starter requests and portable skill downloads. It distinguishes the tool from generic siblings by naming CRO-specific outputs, but it does not explicitly differentiate itself from run_cro_skill.

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

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

There is no explicit guidance on when to use this tool versus alternatives like run_cro_skill. The statement 'No account or credits needed' is a useful condition, but it does not explain when to choose this listing tool over other CRO-related tools.

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

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

Annotations already declare destructive/idempotent/openWorld, but the description adds substantial context: the 2 MB page ceiling, public no-login access, that republishing the same name replaces the page while the link keeps working, and that no styling is added. It does not contradict any annotation, though permissions/auth requirements are left implicit.

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 cost ('Free. Takes HTML you wrote and hosts it...'), and most sentences carry actionable content. A few clauses are flavor/justification ('which is what a report somebody sends every month needs') that could be trimmed.

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 conveys the return implicitly through the URL pattern and link-persistence behavior, and covers hosting constraints, no-templating, and update semantics. It is complete enough to invoke correctly, though it never explicitly states what the call returns.

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 constraining the html parameter to plain image URLs via get_asset and by explaining the 2 MB ceiling rationale and slug reuse intent ('use the client's name in the name').

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 ('takes HTML you wrote and hosts it at postclick.ppc.io/r/<name>') with the concrete output and its public, no-login nature. This clearly distinguishes it from siblings like share_page, build_page, and export_page by naming the hosting target and the no-templating behavior.

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

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

Gives explicit when-to-use and when-not-to guidance: use plain image links from get_asset with as: "url" here, whereas inlining is only for documents that block external images. It also explains re-publishing the same slug to update a recurring report and advises using the client's name.

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

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

Beyond the readOnly/idempotent annotations it discloses concrete behavior: it never starts an audit, spends credits or publishes, and it reports missing evidence and ambiguous page matches explicitly rather than silently guessing. It also states output-contract rules (no free/guarantee/rating claims unless confirmed, audit suggestions are not verified facts, no placeholders like $X, don't infer a free quote from a form alone). That is substantial disclosure the structured fields do not carry.

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

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

The content mostly earns its place, but the ordering is poor: usage and output-discipline rules are front-loaded while the actual 'what this does' sentence sits mid-paragraph. Several hyper-specific rules ('a quote form alone does not mean a free quote') read like skill content rather than tool documentation, bloating the definition's surface.

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 6 params at full schema coverage and no output schema, the description appropriately explains the return contract ('source material for you to turn into the requested deliverable') instead of enumerating fields. It covers safety, scoping and failure modes; the only gap is that parameter usage is left almost entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already explains page, skill, latest, context, section and audit_id thoroughly, including the dashboard-link extraction rule. The description adds essentially no new parameter-level syntax or semantics beyond the 'one change for a first-fix request' hint, 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 concrete operation: 'Finds an existing audit by page URL or client name and retrieves the selected skill plus its relevant evidence in one call.' It also delimits itself from adjacent tools by clarifying it 'returns source material... not a new AI analysis' and 'never starts an audit' — a real distinction from audit_page/ask_audit/list_cro_skills. However, the actual purpose statement is buried mid-description after a block of output rules, and no sibling is named by name.

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 opens with an explicit trigger list: 'Use when the user wants page fixes, message match, buyer objections, copy rewrites or a client test brief,' which maps cleanly onto the five skill enum values. It also gives per-skill selection guidance via the schema and a scoping rule ('Use one change for a first-fix request'). No explicit 'when not to use' or named-alternative routing is given, so it stops short of a 5.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=true), but the description adds real value beyond them: it discloses that saving the same key replaces the prior value, that data is opaque to the audit engine and cannot affect Postclick behavior, and that it costs nothing. That resolves the main agent concerns for a mutation 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?

Front-loaded with the free/opaque-payload framing, then the overwrite rule, then the read path. Slightly conversational and longer than strictly necessary, but every sentence carries information (cost, opacity, replacement, retrieval).

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 free-form key/value store with no output schema, the description covers everything needed: what values are accepted, what a subject URI is, what happens on key collision, that the engine ignores it, and how to read it back. Nothing an agent needs in order 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: 'any name, any value', the fact that re-saving a key overwrites it, and that a subject is 'any record' addressed by URI. This clarifies key uniqueness and value freedom beyond the field-level 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 (save/attach) and resource (notes on a record), and explicitly distinguishes itself from the sibling `get_notes` by naming it as the read path. An agent can tell it apart from the other audit/page tools 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 context in which to use it ('so the work you do around these audits survives between conversations') and names the read alternative `get_notes`. It does not state when NOT to use it, but the intended scenario is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds non-obvious traits those annotations cannot express: that the call is 'Free', that results are addresses intended for fetch rather than full records, and that an empty query degrades to a recency listing. It stops short of pagination or limit interaction beyond what the schema says.

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 value proposition and return shape, then layers usage, then the empty-query fallback, with no filler sentences. Length is justified by the number of distinct behaviors it must convey for a general-purpose search.

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 carries the return-shape burden and does so ('an address for each hit'), plus cost, zero-arg behavior, and the natural follow-up tool. For a 4-param optional-args search over a large sibling set, 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 coverage is 100%, so all four parameters are documented in the schema already, including the empty-query and kind-omission behaviors. The description restates these ('Leave the words empty', 'Use kind=audit') rather than adding syntax or format detail beyond them, so the baseline of 3 is correct.

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

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

States a specific verb and resource — finds any work in the workspace by words — and immediately frames the result as 'an address for each hit that you pass straight to `fetch`', which separates it cleanly from the sibling fetch tool and from get_* lookups. An agent knows exactly what this returns and what to do with it.

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

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

Gives concrete trigger conditions with quoted user phrasings ('the zoomdrain page', 'last month's audit'), states the zero-arg behavior ('Leave the words empty to list the most recent of everything'), and pre-empts a likely detour with 'an account overview is not needed first'. Explicit when-to-use plus a routing rule to kind=audit.

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 flag a non-idempotent, non-read-only, open-world operation, and the description adds the crucial behavioral detail the annotations cannot express: for a build, minting a new link revokes the previous one, while a design link is stable and repeatable. It also notes the link is free and requires no login for the recipient.

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 key use case; every sentence carries operational information (routing, exclusivity, revocation). It is on the longer side, but no sentence is filler, so only a small deduction for density.

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 covers what the agent needs: what the link returns (one stacked page, PDF-printable), which parameter selects which resource, the exclusivity rule, and the revocation/idempotency difference between the two paths.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: concept_id produces a single stacked page that reads as a whole design and prints to PDF, build_run_id shares a finished built page, and the two are mutually exclusive. That mutual-exclusion rule is not in the schema and materially affects invocation.

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 action (mints a public no-login link) and resource (design or built page), and explicitly distinguishes itself from the login-walled dashboard/app link and from export_page. An agent can route here correctly without inspecting other 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?

It gives explicit when-to-use scenarios ('send me the designs', 'forward this to my client'), explicit when-not (never hand over a dashboard/app link), names the alternative (export_page) for source-file requests, and states the mutual exclusivity of the two ID parameters.

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