Tyton

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

Beyond the annotations it discloses retry semantics ('a repeated request_id is treated as a retry of the same request'), the per-installation gate ('the start runs only after the matching installation has fresh verified callbacks'), the auth/feature prerequisites (paired server key, approval and execution features), and explicit non-behaviors ('sends nothing now, bypasses no checks'). Annotations give the safety profile; the description gives the operational contract.

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

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

Front-loaded with the action, then prerequisites, then exclusions; six dense sentences with little repetition. A few clauses are packed (the scope/key/feature sentence) but nothing is wasted for a destructive, multi-constraint 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 output schema and 0% parameter coverage, the description covers preconditions, gating, idempotency and exclusions well enough to call the tool safely. It leaves the digest/revision semantics and any post-call state expectation to inference.

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 0%, so the description must carry the load, and it does name all five inputs and pin required values for confirmed and customer_confirmation.scope, plus the identification triple and request_id retry meaning. It does not explain what revision or digest actually represent (e.g. the 64-hex plan hash), leaving some semantic gaps.

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 precise compound verb+resource: it records approval of an unchanged conversion plan proposal AND records one start request, identified by revision/digest/request_id. That distinguishes it in substance from approve_conversion_plan (approval only) and stage_conversion_installation, but no sibling is named explicitly, which is the 5-level criterion.

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 preconditions for use ('after the customer explicitly accepted that scope in chat', requires confirmed:true and customer_confirmation with scope approve_and_start_after_checks) and negative conditions ('does not resume a paused, revoked, changed or restaged installation'). It stops short of naming the alternative tool to call when you want approval without a start request.

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

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

Annotations only say destructive/idempotent/not-read-only; the description adds substantive behavior: stale or changed revisions are rejected, the key can approve only its own project, provenance is connected-agent rather than verified human, and approval does not activate tracking or authorize live Meta events. This is context an agent cannot get from 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?

Front-loaded with the core action before constraints and exclusions; every sentence carries weight. It is dense across five sentences but none are filler or restatement of the name.

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 and a fully required nested-parameter set, the description covers preconditions, rejection behavior, authorization scope, and what the action does not do. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0% with a nested object, so the description must carry the load. It explains confirmed: true, the required customer_confirmation scope of approve_plan, and that revision/digest identify an unchanged proposal with stale revisions rejected — a real gain. It stops short of saying the digest is a 64-hex hash of the proposal content, leaving some detail to the schema pattern.

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 precise verb+resource ('Records approval of an unchanged conversion plan proposal') and immediately scopes it against the sibling approve_and_start_conversion_plan with 'Approval only: does not activate tracking or authorize live Meta events.' An agent can select this tool without opening a schema.

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

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

Gives explicit preconditions (customer must have explicitly accepted in chat, requires confirmed: true and customer_confirmation with scope approve_plan) and names the alternative path ('The customer can also approve in the signed-in report'). When and when-not are both covered.

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

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

With annotations already declaring readOnlyHint=false, destructiveHint=true, idempotentHint=true, the description adds real context beyond them: the write is a 'partial audit report', agent-supplied HTML is stored as 'unverified evidence', one session can hold several components, and the return set is explicitly bounded ('evidence, limitations and discovery actions, not a full tracking-health verdict'). It does not explain what destructiveness/revision overwrite means, which is a gap given destructiveHint=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?

Effectively four sentences, front-loaded with the core action and scope, with no filler. It is dense but every clause carries information; only the session/return-value sentence could be tightened.

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

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

An output schema exists, so omitting return-field detail is fine, and the safety profile is carried by annotations. The description covers scope, evidence trust level, and session grouping, but given the large audit-lifecycle sibling family it leaves the agent guessing about sequencing (begin_audit → audit_site → submit_findings).

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 schema itself documents all seven parameters thoroughly (audit_key as a secret capability, revision semantics, request_id retry behavior). The description only loosely gestures at them ('the audit session fields and the page URL, plus optional sanitized HTML'), adding little beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource ('Inspects one public page's HTML and saves a partial audit report') and scopes it clearly ('one session can hold several related components', 'not a full tracking-health verdict'). An agent can distinguish it from read-only siblings like read_audit or tracking_status. The relationship to lifecycle siblings begin_audit / record_audit_context / submit_findings is not spelled out, so it falls short of a 5.

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

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

Usage is only implied: 'without signup' and 'verifying a change' (via the fresh parameter) give contextual hints, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many audit siblings. The agent must infer that this is the single-page inspection entry point versus begin_audit or read_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 already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered; the description adds real value beyond that by disclosing the returned private capability (audit_id + audit_key), revision 0, the retry-safe request_id, and the security scoping ('covers only this audit record, not access to the website').

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 core action in the first clause, then layers return values, the no-persistence guarantee, and the capability's scope. Four tight clauses with essentially no filler, though the sentence packs several distinct facts that could be slightly easier to scan.

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

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

An output schema exists, so return-shape detail is optional, yet the description usefully explains what the capability is and its limits. For a one-parameter, non-destructive bootstrap tool, an agent has everything needed to call it correctly; only explicit sequencing guidance toward the sibling save tool is missing.

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

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

Only one parameter (url) and schema description coverage is 0%, so the description carries the burden: it names the URL as the target of the audit, matching the schema's uri format. It adds no format, validation, or normalization detail beyond that, which is adequate but minimal for a single obvious input.

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 ('Starts a new free audit session for a URL') and immediately clarifies what it is not: 'Saves nothing,' distinguishing it from read_audit/audit_site and the record_* siblings. An agent can tell this is the session-bootstrap step rather than an evidence-writing or reporting step.

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 ordering (begin an audit, then save evidence with the returned request_id), but it never names an alternative tool or states an explicit when-not condition. Usage is inferable from the surrounding narrative rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine extra context: the 24-hour lookback window, that it 'sends no events and grants no approval', the connected-site precondition, and an explicit scope boundary (not business outcomes, traffic, attribution, or Meta delivery).

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 check, then parameters, then read-only status and scope limits. Dense but each clause carries weight; the run of negative exclusions is slightly heavy but defensible for a verification 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?

A read-only verification tool with no output schema, and the description adequately covers scope, time window, what is excluded, and the precondition. It stops short of describing the actual response shape (per-event receipt result), which would be the final missing piece.

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?

Reports 0% schema coverage, but the nested event schema actually carries field descriptions, patterns, an enum, and maxItems. The description adds the 'up to 20 unique' constraint and clarifies the installation/event-pair shape, which is useful but largely overlaps with the schema; a 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: verifying whether PageView/conversion event IDs from an activated live installation reached Tyton's dashboard storage within the last 24 hours. This is easy to distinguish from siblings like verify_install, tracking_status, or get_setup_progress.

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

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

Gives clear context for use (post-activation receipt verification, event/source pairs) and an explicit exclusion ('Verification callbacks are not live events') plus a precondition ('Requires a connected site'). It stops short of naming alternative sibling tools for adjacent questions, so not a full 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 declare destructiveHint=true and idempotentHint=false; the description adds genuinely new behavior the annotations cannot express: the code is single-use, expires in 15 minutes, and the returned keys are shown only once. It does not spell out that the consumed code becomes invalid or what permissions the new keys grant, but it goes well beyond the annotation surface.

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

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

Two dense sentences, front-loaded with the action and input source, then the return contract. No filler and nothing repeated from the title.

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

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

With no output schema, the description correctly carries the return contract (server key and browser key, shown once, plus host configuration examples) while also covering input provenance and expiry. An agent has everything needed to call it and handle 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 description coverage is 100%, with the code format (7K2M-QX4T, dashes optional) and the client enum already documented in the schema, so the baseline is 3. The description adds only that the code is single-use with a 15-minute validity window, which is marginal extra meaning over 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 (Connects) and resource (a Tyton site to this connection) plus the mechanism (single-use pairing code). It is clear what the tool does, though it never names which sibling to use instead (e.g. setup_server, check_live_setup), so an agent must infer its place in the setup flow.

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

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

Gives a concrete prerequisite and source for the input: the code comes from the site's card on usetyton.com and is valid for 15 minutes. Usage context is therefore clear, but there is no explicit when-not guidance or comparison to the many sibling setup/connection tools.

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

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

Goes well beyond the annotations' destructiveHint/idempotent flags by specifying what is destroyed, what is explicitly left intact (subscription, billing, website, Meta dataset), and residual effects (snippet/SDK persists, a loaded Pixel keeps sending until reload, in-flight Meta requests cannot be recalled). This is exactly the blast-radius detail an agent needs before a destructive call.

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

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

Front-loads the destructive action and scope before the guards and side effects, and nearly every sentence carries distinct information. It is dense, and the closing 'Requires a connected site' mildly restates the earlier connected-project framing.

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 no output schema, the description covers the action, the safety guards, the blast radius, and the residual side effects. An agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it explains that confirmed must be true and that expected_url must equal the connected project's current URL, with a no-op fallback on mismatch. It does not specify URL format or length bounds, but the guard semantics are conveyed.

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 ('Permanently deletes') plus the exact resource ('the Tyton project connected to this connection') and enumerates the scope of what is destroyed (keys, setup, event history). No sibling tool performs deletion, so the destructive action 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?

Gives clear preconditions ('Requires confirmed: true and expected_url equal to the connected project's current URL; nothing is deleted if they differ') and a state requirement ('Requires a connected site'). It does not name alternatives or when-not-to-use beyond the URL guard, so it stops short of 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 and destructiveHint=false, so the safety profile is covered; the description nonetheless adds real context: the download authenticates with the connection's server key, no npm publisher account or repository access is needed, and the call does not install, approve, start tracking or send events. That is meaningful added value beyond the structured fields, though return/format details stay thin.

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 doing distinct work: what is returned, how authentication works, and the negative guarantees plus precondition. The most decision-relevant content (what it returns) is front-loaded with no filler.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the payload (download, SHA-256 checksum, install steps). The precondition and the read-only guarantees round out what an agent needs before invoking a zero-argument 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 takes zero parameters, and the registry notes 0 params with 100% schema coverage, so the baseline is 4. There is no parameter surface for the description to clarify or omit.

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 ('Returns the private Tyton server SDK download, its SHA-256 checksum and the local-file install steps') and scopes it to the connected project. It is clearly distinguishable from install-executing siblings like setup_tracking, verify_install or approve_conversion_plan.

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 a clear precondition ('Requires a connected site') and implicitly frames when to use it by ruling out install/approve/track behavior, so the agent knows this is the 'get instructions' path rather than the 'perform install' path. It does not name a specific alternative tool to prefer in a given situation, 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 already declare readOnly/idempotent/non-destructive, and the description usefully expands them: it clarifies read-only means no approval, no activation, and no test events sent, notes the callback-evidence caveat ('not business success or Meta receipt'), and gives a credential prerequisite. That is meaningful added context beyond the structured hints, though it omits any latency/rate or return-shape notes.

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 what it reads, then stacks the read-only and caveat clauses. It is dense and every clause carries information, though the telegraphic fragments ('Read-only: makes no approval or activation...') read a bit choppy rather than smoothly structured.

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 helpfully enumerates the returned facets, so an agent knows what to expect. Combined with the read-only confirmation and prerequisite, it is complete enough for a zero-param read tool, though it does not explain the format of the 'single next step' or how the state is keyed.

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). No parameter-level detail is needed or expected 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 resource ('connected site's setup state') and enumerates the exact facets returned (plan approval, installation generation, missing callback sources, pauses, next step). It is clear on its own, but it never names or contrasts the many overlapping siblings (check_live_setup, setup_status, tracking_status, verify_install), so an agent cannot definitively disambiguate from the description alone.

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 this is the read-only progress surface and states a prerequisite ('Requires a connected site') and a scope note ('Verification-only setup works without Meta credentials'). However it gives no explicit when-to-use/when-not guidance against the numerous sibling status tools, leaving the selection 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 readOnly/idempotent/non-destructive/non-open-world, so the description earns credit for the details they do NOT provide: the three non-terminal states (waiting, unavailable, expired), the credential payload delivered on approval, the 5-second polling cadence, and the caveat that a connection is not tracking approval or activation. This is meaningful operational context 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?

The action is front-loaded, followed by return states, polling cadence, and a caveat, all in a compact block with no filler. The closing sentence ('A connection is not tracking approval or activation') is a little cryptic, slightly blunting readability.

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 assumes the burden of describing returns and does so (waiting/unavailable/expired vs full credential payload), plus polling guidance and a caveat. It is nearly complete for a 2-param read tool; only parameter format/error semantics are left thin.

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 0%, so the description must compensate. It names both parameters and usefully labels poll_token as 'private', signalling it is a secret, but it does not explain the uuid vs 64-hex formats or failure behavior for a bad token. It adds some meaning but leaves the low-coverage schema under-documented.

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: it 'Checks a signup and Connect request' using request_id and poll_token, and clarifies that it returns connection credentials after approval. This distinguishes it functionally from start_signup (initiation) and the other status tools, though it never explicitly names a sibling to route against.

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 rather than stated: the 'suggested polling interval is 5 seconds' tells the agent it is a poll-after-startup tool and the poll_token/request_id pairing shows the expected flow. There is no explicit when-not-to-use condition or named alternative among the many status/setup siblings.

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 non-read-only, idempotent, destructive, and non-open-world, and the description adds real depth beyond them: the optimistic-concurrency rule (document.revision must equal expected_revision + 1), the retry semantics of a repeated request_id, the validation envelope (slugs, HTTPS origins, official Meta event names, path without query/fragment), and the return payload. It does not explain what the destructiveHint=true annotation actually destroys (presumably a prior draft), which is the one 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?

Front-loads the purpose and the scope exclusion before the constraint list, and every clause carries a real constraint. It loses a little efficiency by restating the document object shape ({schemaVersion, revision, conversions:[...]}) that the schema already expresses structurally, but the accompanying semantic rules are not duplicative.

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 nested 3-parameter mutation tool with no output schema, the description covers inputs, validation limits (1-50 conversions, 1-20 targets, 100 total, 32 KiB), and even the return values (saved proposal, open questions, review link). The only incompleteness is that the destructive annotation is left unexplained relative to a 'draft' save.

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 0%, so the description carries the full burden and largely succeeds: it defines the document shape, the relationship between expected_revision and document.revision, the idempotency meaning of request_id, and semantic rules for ids, labels, event names, origins, paths, and success kinds. It could have added per-field meaning for expected_revision on a fresh site (0), but the concurrency formula covers the essential case.

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

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

States a specific verb and resource ('Saves a conversion plan draft for the connected site') and immediately bounds the scope with 'Does not approve or activate it', which cleanly separates it from the approve_conversion_plan / approve_and_start_conversion_plan siblings. An agent can route between draft-saving and approval 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?

The negative scoping ('does not approve or activate') tells the agent this is the draft path and implies the approval siblings handle the other path, and the revision/idempotency rules give operational context for calling it. However, no alternative tool is named explicitly and there is no statement of when to choose this over read_conversion_plan or stage_conversion_installation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description still adds real value by disclosing a capability boundary ('does not verify the site's backend or grant access to it'). It does not cover failure modes for an invalid or expired key, which keeps it from a 5.

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

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

The purpose is front-loaded in the first clause, and the return payload is enumerated compactly in one sentence. The closing read-only sentence is largely redundant with the annotations, costing a bit of tightness.

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

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

With an output schema present, the description is not obligated to enumerate return fields (it does so anyway), and the annotations cover the safety profile. The remaining gap is error/authorization behavior for a bad audit_key, which matters for a capability-gated read.

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%: revision and request_id are documented in the schema, but audit_id and audit_key are not, and the description only gestures at key semantics via 'private capability' without explaining that the 64-hex key is the authorization secret or how the two required params interact.

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 an existing audit') and enumerates what it returns, so the agent knows exactly what the call produces. It does not differentiate itself from related siblings such as begin_audit, record_audit_context, or submit_findings, so it falls short of a 5.

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

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

The phrase 'using its private capability' implies the caller must already hold the audit_key, and the read-only boundary line hints at when this tool is appropriate, but there is no explicit when-to-use routing against the sibling audit/record tools. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the 'Read-only' line largely restates that, but the description adds genuinely non-obvious interpretation warnings: a verified callback proves receipt only, matching pending approve-and-start requests activate automatically after a fresh current-key check, agents cannot activate manually, and active authorization does not prove live deployment. These materially shape how the agent should treat the returned data.

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 resource and read-only status in the first two sentences, then layered caveats. It is on the verbose side and packs several distinct activation-flow facts into one long sentence, but nearly every clause carries interpretive value rather than filler.

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

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

For a zero-parameter read tool with no output schema, the description does a good job naming the categories of data returned (bindings, signals, active/paused state) and warning about over-interpretation. It stops short of describing the shape of the returned payload, which is the one gap given there is no output schema.

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

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

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly adds no parameter detail and instead spends its words on result interpretation.

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 well-defined resource (staged callback bindings, verification signals, installation state for the connected site), so the agent knows exactly what comes back. It is distinguishable from plan-oriented siblings (read_conversion_plan) but does not explicitly differentiate itself from verify_install, check_live_setup, setup_status, or get_sdk_installation.

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

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

The description never says when to call this versus the many similar read tools (get_sdk_installation, setup_status, tracking_status, verify_install, check_live_setup). The remarks about activation and manual activation are behavioral context, not usage routing, so the agent is left to infer the trigger 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint, so the added "Read-only" is largely redundant. The description does add that it reads a *draft* with *open questions* and *approval state*, which hints at the mutable workflow state being observed, but it discloses no further traits such as what happens when no plan exists.

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

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

Two compact sentences with the action and scope front-loaded and the read-only guarantee appended. Every clause carries information about what is retrieved; there is no filler or repetition.

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

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

With no output schema, the description carries the burden of describing return content, and it does so by enumerating the draft, open questions, approval state and review link. What is missing is edge-case behavior (e.g., no plan yet, not connected), a small gap for a state-reading 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 takes zero parameters, so the schema baseline is 4 by rule. Nothing in the description needs to explain parameter syntax, and it correctly adds no spurious parameter guidance, though it also cannot add meaning where none exists.

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 resource ("conversion plan") and further enumerates the scope of what is read: the draft, open questions, approval state and review link. This distinguishes it functionally from the approve/propose siblings, but it never names those siblings or explicitly contrasts itself with them, so sibling differentiation is implicit rather than stated.

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

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

The word "current" and the emphasis on draft/approval state imply this is the inspection step before acting via approve_conversion_plan or approve_and_start_conversion_plan, giving implied workflow guidance. However, there is no explicit when-to-use statement, no named alternative, and no exclusions, 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context: it returns static reference text rather than mutable state or delivery proof, and it characterises what two of the topics contain. It does not describe output volume or format, keeping it from a 5.

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

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

Front-loads the core behaviour, then the two high-value topics, then the remaining topic names in a compact list, closing with the read-only caveat. Dense and mostly waste-free, though the long comma-separated topic enumeration is a slightly heavy tail.

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 a simple read-only contract, the description covers purpose and the read-only distinction adequately. However, thirteen of the fifteen topic values are named without any indication of what they return, leaving an agent to call blind on most inputs.

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% (topic documented only by its enum, step has a schema description). The description enumerates the full topic list and clarifies that 'step' is 'optionally a single step' scoped to meta_setup, but explains the content of only two of the fifteen topics, so it only partially compensates.

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 Tyton guidance on one topic') and distinguishes the tool from the family of stateful siblings by noting it is 'read-only reference text, not saved checklist state or proof of delivery.' It stops short of a fully explicit contrast with each read_* sibling, but the resource is unambiguous.

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

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

The closing clause 'Read-only reference text, not saved checklist state or proof of delivery' functions as a when-not guide, steering agents away from using this for progress/state checks (get_setup_progress, check_live_setup). No explicit 'use this when you need documentation on X' sentence, so not a full 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?

Goes beyond the annotations by disclosing merge semantics ('Earlier topics are kept; a new answer replaces the same topic'), a validation rule, and a downstream effect ('A public-only choice allows a partial report without further access requests'). These clarify the destructiveHint=true/idempotentHint=true profile, though permission/auth requirements are only implied by the schema.

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

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

Five sentences, all information-bearing, with the core purpose front-loaded. Slightly dense but no filler; the merge-behavior and side-effect sentences each earn their 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 destructive, nested-schema mutation with an output schema present, the description covers the key semantics (topic merge behavior, source requirement, report side effect) without needing to restate return values. Remaining gaps—auth via audit_key and revision/request_id mechanics—are handled by the schema descriptions.

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 67% schema coverage, the description usefully explains the two most semantically complex parameters: audit_scope's choice between continuing the investigation and public_only, and availability_expectation's expected/unexpected meaning. It adds real meaning beyond the schema for these nested params, though url/audit_id/revision/request_id are left to 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 ('Saves answers about one audited component to the audit') and names the concrete topics being written. However, it does not differentiate itself from nearby siblings like record_audit_runtime or submit_findings, so an agent must still infer the boundary between 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?

Provides implied usage through constraints ('Both must have source human_reported') and the consequence of the public-only choice, but never states when to use this tool versus an alternative, nor any when-not condition. Usage is inferable rather than explicit.

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 (write, idempotent, destructive), so the bar is lower, yet the description still adds real behavior: the unknown-state fallback for non-proving evidence types and the return payload ('updated findings and report link'). It does not explain why destructiveHint=true for what reads as an append, nor that audit_key is the authorizing secret — those gaps keep it from a 5.

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

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

Four tight sentences, front-loaded with the core action and followed by the negative constraint, the edge-case rule, and the return. Efficient overall, though the 'sanitized observations... without payloads' clause partially restates the schema's evidence field 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?

With an output schema present, the description need not detail return values, and the brief return note is sufficient. It covers the append semantics, the source types, the fallback rule and the consent/time dimensions, leaving only the audit_key authorization prerequisite and the destructive-write consequence unexplained for an 8-param mutation.

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%: the write-control params (audit_id, revision, audit_key, request_id) are documented in-schema, while required params url, observed_at, consent_state and checks are bare. The description touches consent state, observation time and sanitization ('without payloads, identifiers or credentials'), but that sanitization note duplicates the schema's evidence description and adds no format or enum mapping.

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 ('Saves bounded runtime evidence to the same audit run') and enumerates the evidence sources (browser, backend inspection, destination UI). It differentiates functionally from browser-running siblings via 'Does not run a browser or send events', but never names the sibling tools it must be distinguished from (record_audit_context, submit_findings), leaving the routing to inference.

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 negative guidance ('Does not run a browser or send events') implies this is for supplying evidence already gathered rather than collecting it, which steers the agent away from audit_site/check_live_setup. However, there is no explicit when-to-use statement, no prerequisite for obtaining audit_key/revision first, and no named alternative for the collection case.

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

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

The description adds the prerequisite (connected site) and clarifies what the link does and does not mean ('not proof that tracking works'), which annotations do not cover. However, with destructiveHint=true it never discloses what the link overwrites or whether re-linking replaces an existing report, leaving the destructive behavior opaque.

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

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

Four short sentences, front-loaded with the action and scope, and each sentence adds a constraint or caveat. Slightly denser than needed but no filler.

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

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

For a single-parameter mutation with annotations covering safety and idempotency and no output schema, the description is nearly sufficient: it covers the prerequisite, the acceptance rule, and the meaning of the link. Only the overwrite/idempotency behavior remains 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?

With 0% schema description coverage and one parameter, the description carries the semantic load: it explains the argument is the report URL and adds a validation rule the schema's regex cannot express, namely that only a report for this exact website is accepted.

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 (Links) and resource (an existing Tyton audit report to the connected website's Get Started checklist), which is unmistakably distinct from siblings like save_capi_token, record_audit_context, or audit_site. An agent can select 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?

Gives clear conditions: requires a connected site, only a report for this exact website is accepted, and it completes the checklist's audit step. It doesn't name an alternative tool or state exclusions against siblings, so it falls 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 only declare the generic profile (write, destructive, idempotent, open-world); the description goes well beyond that by disclosing that the token is stored encrypted, is never returned, that Meta validation rejects only explicit invalid/expired responses, and that a saved token leaves delivery unchecked. That is exactly the non-obvious behavior an agent needs before invoking a write 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?

The core action and input rule are front-loaded in the first sentences, followed by validation and side-effect caveats. It is slightly long at six sentences and the 'does not send a test conversion... prove delivery' clause overlaps with the earlier 'delivery unchecked' statement, but every sentence 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 still covers the success path (encrypted, never returned) and the failure semantics (invalid/expired rejected), plus the auth/plan prerequisite — sufficient for a 3-parameter write tool. It is only marginally incomplete in not describing what the call returns on success beyond the token itself.

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 33%, so the description must compensate, and it does: it explains the XOR constraint between capi_token and sealed_capi_token, the raw-vs-sealed distinction, the `tyton_sealed_v1.` prefix, and the Pixel-matching requirement for pixel_id. It stops short of describing the pixel_id numeric pattern or capi_token length bounds, which remain schema-only.

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 ('Saves a Meta Conversions API token for the connected site's current Pixel'), tying it to a precise object rather than a generic save. It is clearly distinct from siblings like setup_tracking, approve_conversion_plan, or verify_install, and an agent can route to it without opening another 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 concrete preconditions ('Requires a connected site with an active Tyton plan', Pixel ID must match the site's saved Pixel) and the selection rule for the two token inputs ('exactly one of capi_token or sealed_capi_token'). It also enumerates what the tool does NOT do (no test conversion, no activation, no delivery proof), but it never names a sibling to use for those adjacent tasks, so routing is left implicit.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true, so the safe/unsafe profile is covered. The description adds genuine scope context ('Does not install an integration or prove provider support') and the returned contract, but never explains the destructive side — that previously stored answers are overwritten or that an empty checkout_domains clears storage — which is the one thing an agent invoking a destructive-hinted tool most needs spelled out.

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, front-loaded with the action and its data payload, followed by limits and a precondition. Slightly redundant in the 'does not install / activation are separate' pairing, but nothing is padding.

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

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

There is no output schema, and the description usefully summarizes the return as the reviewed server SDK success-callback contract, plus it states the connected-site prerequisite. The remaining shortfall is the absence of any note on overwrite semantics for a tool flagged destructive.

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 per-field descriptions and three enums, so the schema carries parameter meaning. The description names only a subset of the six fields (payment provider, landing type/route, checkout domains) and adds no format or constraint detail beyond the schema, 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 (Saves) plus the exact resource (checkout and landing answers) and enumerates the fields involved (payment provider, landing type/route, checkout domains), then names the return value. It also draws a boundary against adjacent operations ('Does not install an integration'), which lets an agent separate it from stage_conversion_installation or verify_install without opening a schema.

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

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

Gives a clear precondition ('Requires a connected site') and states what this step is not, noting approval and activation are separate. It does not, however, name a specific alternative tool or spell out the when-not scenario, so an agent still infers routing rather than being told it.

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

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

The annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond them by naming the connection prerequisite and listing the specific returned configuration areas, though it does not elaborate on response structure or edge cases.

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 compact and front-loaded: it states what is read, marks the operation read-only, clarifies boundaries, and gives the connection prerequisite. Each sentence contributes information without redundant restatement.

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 configuration tool with no output schema, the description provides enough context to invoke it correctly: it identifies what is returned, confirms read-only behavior, states the connection requirement, and excludes unrelated operations. Nothing essential 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?

The tool takes no parameters, so there are no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on behavior and returned content rather than inputs.

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

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

The description gives a specific verb ("Reads") and resource (the connected project's configuration) and enumerates the exact configuration fields returned: site URL, Pixel ID, token status, and saved checkout answers. It also rules out adjacent concerns like plan approval, callback verification, activation, and Meta receipt, making the tool's scope clear among many siblings.

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

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

It states an explicit prerequisite ("Requires a connected site") and clearly excludes what the returned configuration and token status are not. It does not, however, name a concrete alternative sibling tool for related setup checks, so the routing guidance is strong but incomplete.

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 explaining that the same tool is effectively read-only in one invocation shape and destructive in another, and by stating the guard (confirm_change) for Pixel/site switches, which directly explains the destructiveHint=true. Minor tension between 'read-only' wording and readOnlyHint=false, though the conditionality makes it consistent rather than contradictory; prerequisites like 'connected project' are asserted but not defined.

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 tight sentences, each carrying distinct information, with the discover-vs-configure fork stated first and the guard/exclusion following. No repetition of schema or annotation content.

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

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

With no output schema, the description usefully indicates that the read-only path 'returns setup guidance', and it covers the mutation path's guard. It leaves gaps on what happens with an unknown/invalid pixel_id or what a 'connected project' prerequisite actually requires 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 coverage is 100%, so the baseline is 3, but the description adds real relational semantics the schema cannot: pixel_id only triggers a save on a connected project, and confirm_change governs switching an existing Pixel or site. It does not clarify checkout_domains or the name default beyond what the schema already states.

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?

'Discovers or configures reviewed v2 setup for a site' gives a specific verb pair and resource, and the dual-mode explanation makes the tool's identity concrete. It never names a sibling (e.g. setup_status, check_live_setup) it should be preferred over, so differentiation is inferential rather than explicit.

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 clearly splits usage by input: URL-only for guidance, real Pixel ID on a connected project for saving, and confirm_change when switching. 'Does not approve, install or activate tracking' is an effective exclusion but the alternative tools it defers to (approve_*, verify_install) are not named.

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 and idempotentHint=true, and the description extends them by stating exactly what happens: a matching generation resumes, while a new generation 'pauses the previous installation, clears verification and can cancel a pending start'. It also discloses the trusted-success-only reporting contract and the mode:'verify' suppression behavior — unusually rich behavioral disclosure that 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 purpose is front-loaded, which is good, but the paragraph then drifts into tangential implementation detail (the client.conversion(...) invocation signature, PageView/Pixel suppression, closed-widget policy) that reads as developer documentation rather than tool-selection guidance. Roughly a third of the text does not help an agent decide or invoke.

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 four-required-parameter destructive mutation with an empty schema description and no output schema, the description covers preconditions, side effects and operational constraints well enough to call it safely. The main residual gap is the undocumented digest/generation formats and binding cardinality limits.

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 0%, so the description must carry parameter meaning. It partially does: it maps the binding triple to 'conversion, target and a browser or server source' and ties revision, digest and generation to the approved plan revision. But it never explains the digest's 64-hex format, the generation UUID, or the 200-binding cap, leaving gaps the schema alone cannot fill.

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?

It gives a specific verb ('Stages') and resource ('callback bindings ... for the approved latest plan revision and digest under an installation generation'), so an agent can differentiate it from read_conversion_installation and verify_install. However, it never names a sibling tool, and the purpose is buried under dense domain jargon.

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 supplies real preconditions ('Each enabled target needs a source, and Purchase requires a server source') and effectively an exclusion via 'Does not activate tracking', which signals the activation step belongs elsewhere. It stops short of explicitly naming the alternative tool to call for activation or verification.

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 carry the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=true, openWorldHint=false), so the description only needs to add context - and it does: it discloses the returned authorization_url/request_id/poll_token, notes that poll_token is 'private', explains plan-selection behavior, and clarifies that the link 'grants no access and starts no tracking by itself', which meaningfully tempers the destructive annotation.

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 verb and resource, then ordered by input modes, return values, and caveats - a logical agent-readable sequence with no filler sentences. It runs slightly long, and the free-vs-paid plan sentence is peripheral to invocation, but it earns its place as customer-facing context.

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

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

For a 5-parameter mutation tool with no output schema and destructive semantics, the description covers the important ground: return values are enumerated (compensating for the missing output schema), the audit_id/audit_key pairing is described as an alternative to site_url, and consent semantics are stated. The undocumented 'client' enum and the lack of any note on timeouts or link expiry keep it short of 5.

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 20% (just site_url), so the description must compensate, and it does for 4 of 5 params: it explains audit_id+audit_key as a saved free audit that 'brings the report along', restates site_url as the customer's live https site, and defines customer_approved as a consent record. The 'client' enum parameter (codex/cursor/claude_code/other) is never mentioned, which is the one 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?

Opens with a specific verb and resource - 'Creates a Tyton signup and Connect link for one website' - which immediately separates it from connect, audit_site, and get_signup_status. The scope ('for one website') and the two accepted input paths make the intent unambiguous 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?

The description explains the two invocation modes ('either a saved free audit (audit_id and audit_key...) or site_url'), which is real routing guidance, and implies get_signup_status is the follow-up for status polling. However, it never names a sibling tool or states when NOT to use this versus connect, begin_audit, or audit_site, leaving the agent to infer the workflow position.

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 openWorldHint=false, so the safety profile is partly covered. The description adds genuinely non-structured context: findings are stored as "agent-reported, not verified deployed behavior", a group label does not merge reports, and it returns the updated audit decision plus report link. It still does not say what a write overwrites or how a mismatched revision is handled.

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

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

Front-loads the purpose and keeps three short sentences, with the trust caveat ("agent-reported, not verified") placed early where it matters. The first sentence is a dense comma-run listing many data categories, but for a 19-parameter ingestion tool that enumeration earns its length.

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

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

An output schema exists, so return-value detail is not required, yet the description still tells the agent it gets back an updated audit decision and report link. Combined with the trust model, group semantics and unknown-handling rules, an agent has enough to call a complex nested-object tool correctly; only the write/overwrite and revision-conflict behavior remain unstated.

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

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

Schema description coverage is 100% with 19 well-documented properties, many with their own enums and per-field notes, so the schema carries the parameter burden and baseline 3 applies. The description's parameter-level remarks (group is label-only, unknown != failed) largely restate what the schema already says ("legacy grouping label only; does not combine reports"), adding little beyond it.

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

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

Opens with a specific verb+resource pair ("Saves code review findings ... to the audit") and enumerates exactly which findings are captured (server-side events, dedup IDs, Pixel/container presence, payment provider, framework, backend location, existing CAPI quality, reviewed paths, N/A checks). This distinguishes it from read-side siblings like read_audit, though it does not explicitly contrast with the other write-side siblings such as record_audit_context or record_audit_runtime.

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 context is implied through field-level guidance ("Unknown values stay unknown, not failed", "Missing access counts as unknown, not N/A") which tells the agent how to fill the report, but there is no statement of when to call this versus begin_audit, record_audit_context, or save_audit_to_project. No prerequisites about needing audit_id/audit_key/revision are called out as a gating sequence.

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 the description reinforces 'Read-only.' Beyond that it adds real behavioral context: the data is aggregate, not unique, and does not constitute installation verification or Meta deduplication proof, plus the connected-site precondition. It stops short of describing freshness, latency, or response shape.

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

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

Three compact sentences, front-loaded with what is read and what is returned, followed by the interpretation caveat and the prerequisite. Every sentence carries information, though the caveat clause is dense and slightly clause-stacked.

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 must carry the burden of describing returns, and it does enumerate the data categories an agent will get back. It omits any indication of structure, pagination, or time windowing, which is a minor gap for a no-arg read tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description correctly spends no words on inputs and instead characterizes the output content.

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 concrete resource (aggregate browser/server event observations, delivery statuses, crawler-protection mode and counts for the connected site). The scope is materially more specific than the generic 'status' framing of siblings like setup_status or check_live_setup, but it never explicitly names those siblings to force the distinction.

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

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

Provides a prerequisite ('Requires a connected site') and an implicit interpretation warning (counts are not conversions/verification/dedup proof), which is useful. However it gives no explicit when-to-use-this-vs-alternatives guidance against the many other status/verification tools in the sibling set, so usage must be inferred.

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, open-world behavior, so the bar is lower; the description still adds the meaningful constraint that only static HTML is inspected and that runtime callbacks, activation, consent behavior and Meta receipt are out of scope, plus the connected-site requirement. It does not describe pagination or rate limits, but those are largely irrelevant for a single-page check.

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

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

Four short sentences, front-loaded with the core action and scope before the exclusions and prerequisite. Dense with no filler, though the exclusion list could arguably be compressed.

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

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

There is no output schema, so the description carries return-value burden; 'compares them with the connected project' implies a comparison verdict but does not say what the result looks like. For a low-complexity, two-parameter read tool the remaining gap is minor.

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

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

Schema coverage is 50% (only 'html' is documented as 'page HTML fetched by the agent'). The description compensates by explaining the two input paths — a public fetch of the URL versus agent-supplied HTML — which gives the otherwise undocumented 'url' parameter clear meaning and clarifies the mutual roles of the pair.

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 resource (a page's static HTML) plus exactly what it looks for (Tyton container and Meta Pixel references) and the comparison target (the connected project). It also bounds the scope by declaring it does not verify runtime behavior, which cleanly separates it from runtime-oriented siblings like check_live_setup.

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 the two accepted input modes ('a public fetch or HTML supplied by the agent') and the prerequisite 'Requires a connected site', and rules out the runtime cases via the 'does not verify' sentence. It stops short of naming the sibling tool an agent should use for those runtime cases, so routing is implied rather than explicit.

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