AgentPixel

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the write-plus-network nature is partly covered. The description goes further: it discloses that a real homepage fetch occurs, that state is persisted as installed/not_installed, how failures are surfaced via check_error, and the evaluator-account exception where only a fixed staging URL is fetched and redirects are rejected. It does not explain why the operation is non-idempotent, which is the one annotation left unaddressed.

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: the action first, then the two possible persisted outcomes, then the edge-case constraint. No filler, and the most important information 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?

An output schema exists, so return-value detail is not strictly required, yet the description still names install_status and check_error helpfully. Combined with annotations covering the destructive/open-world profile, an agent has enough to call it correctly; only idempotency behavior remains unexplained.

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

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

There is a single parameter and schema coverage is 100%, including an example value and a format pattern, so the schema fully carries parameter meaning. The description adds nothing about pixel_id, which is the correct baseline of 3 when the schema does the heavy lifting.

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

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

The description states a specific verb and resource chain: fetch the pixel's homepage and persist whether the tracking tag is present. That is far more concrete than the name alone, though it never names or contrasts a sibling such as get_pixel or setup_status, so an agent must infer which of those is the right alternative.

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

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

There is no explicit 'use this when...' statement or named alternative. The one usage-relevant detail given is scoping for evaluator accounts (fixed URL, redirects rejected), which is a conditional hint but not guidance on when to pick this tool over the sibling status/get 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 only declare destructiveHint=true and idempotentHint=false; the description adds genuinely useful behavior: every settings change spawns a new policy version and re-prompts returning visitors, and the call returns a policy link plus an embed script tag. It stops short of stating what is destroyed or whether an existing bar is overwritten, so it does not fully cover the destructive hint.

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

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

Three short sentences, front-loaded with the action and followed by the side effect and return value. The return-value sentence slightly duplicates what the output schema already conveys, but it is not wasteful enough to penalize more heavily.

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 a full output schema and complete parameter documentation, the description only needs to carry the behavioral load, and it does flag the versioning/re-consent consequence. It is nearly complete, lacking only a note on whether an existing consent bar is replaced or what destructive means here.

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

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

Schema description coverage is 100%, so all 10 parameters are already documented with examples and constraints in the schema. The description adds no parameter-level meaning (syntax, required-vs-optional tradeoffs, purpose interactions), so the baseline of 3 applies.

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

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

States a specific verb and resource ('turn on and set up the consent bar for a pixel'), which is clearly distinguishable from siblings like get_policy, get_pixel, and create_pixel. An agent can tell this is the configuration mutation, not a read of existing policy state.

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

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

Usage is implied by the setup context ('turn on and set up'), but there is no explicit when-to-use guidance or routing against alternatives such as get_policy for inspecting an existing configuration. The agent must infer that this is the write path when no policy exists yet.

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 annotations, the description discloses high-value behavior: the first successful confirmation returns an api_key that is shown only once and must be stored, the code allows 5 attempts and expires in 24 hours, and the link-polling loop should run at 5-second intervals for up to 10 minutes. These are non-obvious operational and one-time-secret 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?

Front-loaded purpose sentence, then two labeled branches ('Preferred' / 'Link clicked') with no filler. Every remaining sentence carries a distinct operational fact (attempt limit, code lifetime, resend escalation).

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 details needn't be restated, yet the description still explains what the agent must do with the returned secret and the success flag. Combined with the alternative-tool routing, nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds the valid parameter combinations (account_id+code+signup_token for confirmation, account_id+signup_token alone for status checks) that the optional-parameter schema does not express. It does not mention the legacy verification_token path, which only the schema covers.

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 opening sentence states a specific verb+resource ('Confirm the email') and explicitly covers the two distinct modes (code entry vs. polling for a clicked link). An agent can distinguish this from siblings like resend_code or create_api_key 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?

It names the preferred invocation, the alternative invocation, the polling cadence and ceiling (every 5 seconds, up to 10 minutes until email_verified is true), the follow-up call (create_api_key), and the escalation path (resend_code) when the code is exhausted. When/when-not guidance is fully 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 already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description goes further by concretizing non-idempotency (each call mints an additional key) and by disclosing that the secret is shown only once and must be stored securely. That is real behavioral value beyond the structured hints.

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

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

Three short sentences, front-loaded with the action and prerequisite, then the routing rule, then the return/secret-handling caveat. No filler; every sentence carries decision-relevant 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?

An output schema exists, so the description need not describe the response body, yet it still flags the one-shot nature of the returned key. With prerequisites, the sibling alternative, and secret handling all covered, nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100%: account_id and signup_token are already documented, including the token's 24-hour lifetime. The description only reiterates the confirmation prerequisite and adds no 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?

Specific verb+resource ('Issue an API key') with an explicit precondition ('after the email is confirmed'). It also names the sibling confirm_signup, letting an agent distinguish this tool from the signup flow 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?

States an explicit when-not condition ('Not needed when confirm_signup already returned api_key') and a call-count constraint ('Each call issues another key, so call it once'). Both the alternative and the selection rule are spelled out rather than implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the bar is lower. The description still adds real value: it clarifies the API-key side effect does not occur, states the account prerequisite, and describes the install_status lifecycle starting at 'not_checked'. It does not say what happens on a duplicate domain, which is the one notable gap.

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

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

Front-loaded one-line purpose followed by terse, distinct operational notes; no filler, and each line carries a rule the agent must obey (no API key, active account, consent before install, initial status).

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 details are unnecessary. For a mutating tool with only one required parameter, the description covers preconditions, sequencing, and state initialization, which is everything needed to invoke it correctly.

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

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

Only one parameter and schema description coverage is 100% — the schema already specifies the hostname format, pattern, length bounds, and an example. The description adds nothing about the domain argument beyond reassembling 'for a domain', so the baseline of 3 applies.

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

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

States a precise verb+resource ('Create a pixel for a domain') and explicitly excludes a confusing near-neighbor by noting it 'Does not create an API key', which separates it from the create_api_key sibling. An agent can identify this as the pixel-provisioning tool 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 a hard precondition ('The account must already be active'), a required follow-up ('Next: call configure_consent...'), and an explicit ordering prohibition ('Do not install a snippet before consent is configured'). This tells the agent both when to call it and what must happen before/after, including the initial 'not_checked' state.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the description earns credit for going further: new contacts can arrive between reads (no stable snapshot), results are scoped to a single pixel, and evaluation data is consent-gated (synthetic examples only after consent is saved, hidden on withdrawal). It omits rate limits or page-size behavior, keeping it at a strong 4 rather than 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?

Short and front-loaded with the one-line purpose, and every sentence carries information. The phrasing is uneven ('Pass on as a UTC day' reads ambiguously) and the consent sentence is somewhat cryptic, but there is 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 an output schema handling return values, 100% schema coverage, and annotations covering safety, the description supplies what remains: pagination mechanics, eventual-consistency caveat, and consent-gated visibility. Only sibling differentiation is unaddressed, which is a minor gap given the unique resource.

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

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

Schema description coverage is 100%, and the schema already documents 'exactly one of on or after', the YYYY-MM-DD format, and that 'after' is the previous high_water. The description mostly restates this, adding only light framing about the cursor round-trip. Baseline 3 applies when the schema carries the parameter burden.

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

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

States the resource and scope precisely: 'Contacts for one pixel.' The read action is implied by the name/annotations, and 'contacts' is a distinct resource from siblings like get_pixel/list_pixels. It stops short of naming any sibling or explicitly contrasting alternatives, so not 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?

Gives concrete operating instructions: pass 'on' as a UTC day, or 'after' as the high_water from the previous pull, and use high_water as the next cursor. This tells the agent how to drive the tool across reads, but names no alternatives and gives no when-not guidance (e.g. which mode to prefer for which workflow).

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 fully covered by structured data. The description adds one genuinely useful behavioral fact — that the payload includes the HTML snippet needed to install the tag — but says nothing about scoping, permissions, or error 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?

A single short clause with zero filler, and the most important fact (the install snippet) is front-loaded. It is efficient, though the terseness edges toward under-specification rather than pure conciseness.

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, and annotations cover the safety contract. What is missing is the routing information an agent needs to choose this tool over list_pixels or create_pixel, which leaves the definition only minimally complete for its sibling set.

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

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

Schema description coverage is 100%, and the pixel_id param is already richly documented in the schema ('returned by create_pixel or list_pixels, never an account_id', plus an example). The description contributes no additional meaning about the parameter, 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 is a noun fragment ('One pixel, including the HTML snippet...') rather than a verb+resource statement; the action of reading is only implied. The title supplies 'Read pixel and install tag', and the singular 'one pixel' loosely distinguishes it from list_pixels, but the description text itself does not state a clear verb.

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 when-to-use guidance and no mention of alternatives such as list_pixels (for enumerating) or create_pixel (for provisioning). The agent must infer the retrieval context purely from the name and the schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond them by disclosing the consent-off edge case where no policy exists yet, which is genuinely useful behavioral context for interpreting results.

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

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

Two short fragments with no padding; the core output description is front-loaded and the caveat follows immediately. The phrasing is slightly terse/awkward but nothing is wasted.

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

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

With an output schema present, the description needn't explain return values, and it correctly spends its words on the one thing the schema can't convey: the consent-off case where no policy exists. For a one-parameter read tool this is close to 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?

There is a single parameter with 100% schema description coverage, including a pattern and an example value, so the schema fully documents pixel_id. The description adds no parameter-level meaning, which matches the baseline of 3 when the schema does the heavy lifting.

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

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

The description names the specific resource (hosted privacy/data-use policy) and its scope (for a pixel), and states the return form (HTML). It is clearly distinguishable from siblings like get_pixel or configure_consent, though it does not explicitly contrast itself with any of 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?

Usage is implied: read the hosted notice for a given pixel. The description adds one useful precondition ('A pixel with consent turned off has no policy yet'), which warns the agent about an empty/unavailable result. It offers no routing guidance against alternatives, so it stays at minimum-viable.

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, destructiveHint=false and openWorldHint=false, covering the full behavioral profile of this simple read. The description adds no behavioral context beyond that (no pagination, caching, or auth notes), so it contributes almost nothing on this dimension.

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

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

Two short, front-loaded sentences with no filler; the scope statement comes first. It is appropriately sized for a zero-parameter list tool, though the second sentence is somewhat fragmentary.

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

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

With an output schema present, return values need no explanation in prose, and there are no parameters to document. Annotations carry the safety profile, so the definition is essentially complete for a trivial read, missing only sibling routing guidance.

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, which is the baseline 4 case. The description's mention of output fields does not function as parameter documentation, and none is needed.

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 the resource and scope precisely: 'Pixels on this account', which together with the name makes the collection-listing purpose unambiguous. It does not explicitly contrast with the sibling get_pixel (single pixel) or create_pixel, so it earns a 4 rather than 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?

There is no guidance on when to call this instead of get_pixel, create_pixel, or check_install, and no prerequisites or exclusions are stated. The agent must infer from the name alone that this is the collection-level read.

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

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

Goes well beyond the annotations by disclosing rate limits, the side effect that the old code stops working, and the downstream recovery path via POST /v1/accounts/{account_id}/signup-token. This is exactly the operational context an agent needs for a non-idempotent write.

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

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

Three short sentences, front-loaded with the action, then conditions, then limits and side effects. No filler and nothing repeated from the schema.

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

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

An output schema exists, so return values need not be described. Between the action, trigger conditions, rate limits, invalidation side effect, and the follow-up token flow, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and the email property is already documented with format and an example. The description adds the meaningful constraint that the email must belong to an existing account, which the schema does not state.

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: send a new 6-digit code to the email of an existing account. The 'existing account' scoping and the 6-digit code detail distinguish it from siblings like confirm_signup and signup_free without needing 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 explicit trigger conditions ('when the code expired, was lost or was entered wrong 5 times') plus hard limits (1/min, 5/day). It stops short of naming an alternative tool or stating when not to use it, so it is clear context but not 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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds real semantic content beyond that: setup_complete flips only after at least one pixel's tag has been observed on its site, and good_standing describes the account rather than the tag. It stops short of noting staleness, refresh timing, or permission requirements.

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 claim is front-loaded in the first sentence, with the field semantics following as supporting detail. The inherited docstring indentation is slightly untidy but 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?

An output schema exists and annotations cover the safety profile, so the description's obligation is narrow, and it meets it by explaining what the two returned booleans actually mean. The one real omission is routing guidance against the similar check_install sibling.

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 prose instead spends its budget on clarifying the two boolean fields returned, which is appropriate for a no-arg status tool.

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

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

The description states what the tool reports: whether the account can use pixels and whether a tag is installed, which is a specific, checkable outcome rather than a restatement of the name. It does not, however, distinguish itself from the overlapping sibling check_install, leaving an agent to guess which status check to prefer.

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 when-to-use guidance, no prerequisites, and no mention of the apparent alternative check_install (or whoami) despite the obvious overlap in this sibling set. The agent must infer the calling context entirely from the tool 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?

Annotations declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the mutation profile is already known. The description adds genuinely useful context beyond that: no card required, the price after the trial, that an email code is dispatched, and that signup_token expires in 24 hours. It does not warn whether re-invoking creates a duplicate account, which is the main behavioral 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 offer and price, then the mechanics, then the required next call, then the token lifetime. Every sentence carries information, though the pricing sentence is longer than strictly needed for tool selection.

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

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

An output schema exists, yet the description still names the returned account_id and signup_token and tells the agent to keep both, plus the exact signature of the next call and the token TTL — a complete happy-path flow. It omits error/duplicate-account handling and never mentions resend_code as the recovery path for a lost code.

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 three parameters (including the optional trial code) are already documented with patterns, lengths and examples. The description only reinforces that the 6-digit code goes to the email address; it adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource with commercial terms ('Start a 30-day trial, no card... $1 per account per month'), which instantly distinguishes it from sibling signup-adjacent tools like confirm_signup and resend_code. An agent can tell what this does and what it costs 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?

Explicitly prescribes the follow-up flow: ask the person for the emailed 6-digit code, then call confirm_signup(account_id, code, signup_token). That is strong sequencing guidance, but it never says when NOT to use this tool (e.g. when an account already exists, in which case whoami/setup_status would be the right entry point), so there are no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world, so the safety profile is covered. The description adds genuinely non-redundant behavior: no account or key is required, and every record is synthetic and marked as such — important context for a demo tool whose output could otherwise be mistaken for real 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?

Three short lines, front-loaded with the payload contents before the no-auth note and the call-order instruction. Every sentence carries distinct information and none 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?

An output schema exists, so the description need not enumerate return fields, and it still summarizes the sample contents at a glance. Combined with the no-key note and the next-step routing to signup_free, an agent has everything needed to call 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?

The tool takes zero parameters, so the baseline is 4 and there is no syntax or format meaning for the description to add. Nothing here is missing or misleading on the parameter front.

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 exactly what the tool returns — a labeled sample consisting of a pixel, a consent receipt, and two contacts — and the title 'See sample output' supplies the action. An agent can distinguish this preview tool from siblings like signup_free, create_pixel, or get_contacts 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?

It gives explicit sequencing: 'Call this first to show the person what AgentPixel returns, then call signup_free.' That names both the condition for using this tool and the follow-up alternative, leaving nothing to inference.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so the bar is lower. The description adds genuinely useful semantics beyond that: what status means (state after email confirmation), what each plan value means (trial 'free' id, 'paid', 'unlimited'), trial_ends_at, and that key_prefix is a truncated prefix and not the secret key.

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 is front-loaded in the first line and the remainder is a tight list of field meanings with no filler. The multi-line indented formatting is slightly awkward but the content 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?

With an output schema present, the description need not explain return values, yet it adds useful interpretation of the plan/status/trial fields. Combined with full annotations and zero parameters, the definition is essentially complete; only explicit routing guidance 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 zero parameters, so per the rubric the baseline is 4. The description's discussion of returned fields is extra rather than parameter documentation, which is fine.

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 opening line states a specific resource ('the account this connection's API key belongs to'), which is clear and distinguishable from all siblings such as create_api_key or check_install. It is not a bare tautology of the name 'whoami', though it does not explicitly contrast itself with any sibling tool.

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 states when to call this versus alternatives; the agent must infer from the name that this is for verifying identity/account state. There are no prerequisites or exclusions given.

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