Hooky

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the bar is lower, yet the description adds genuinely new behavior: a documented failure mode ('plan_limit' when no free site remains) and the shape of the returned install artifact. It does not cover permissions/scope or what happens to the site's state after creation.

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 earning its place: what it does and returns, the failure condition, and the post-call action. Purpose and return value are front-loaded with no redundant restatement of the title.

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

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

For a 7-parameter mutation with no output schema, the description covers the essential return value (install.script_tag) and the key error case, and the schema handles all parameter detail. Missing only peripheral context such as whether the site is immediately active or any auth/plan prerequisites beyond the limit error.

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 property descriptions are unusually rich (url doubles as first allowed domain and fallback name, theme enum explained, color format given), so the schema carries parameter meaning. The description adds no parameter-level guidance of its own beyond the script tag workflow.

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

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

States a specific verb and resource ('Adds a website to the account') and adds the return payload ('returns it with its install.script_tag'), which separates it cleanly from update_site and list_sites in the sibling set.

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?

Implies creation-time usage and gives a concrete follow-up workflow (paste the returned script tag before </body> in the shared layout), which tells the agent what to do after the call. It never explicitly contrasts with update_site for existing sites, so the when-not is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds value by enumerating the concrete data returned (plan, sites used, site limit, dashboard URL), which matters because no output schema exists. It does not discuss auth failure modes or error behavior, keeping it short of a 5.

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

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

A single front-loaded sentence with a colon-delimited field list; every clause earns its place and nothing is padded.

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

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

With no input parameters and no output schema, the description must carry return-value information, and it does so by listing the main fields. It stops short of describing response shape or edge cases (e.g. invalid key), but is adequate for a simple 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 explain; the baseline of 4 applies. The description correctly implies no input is needed by framing the lookup as keyed off the API key itself.

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 resource and scope: the account tied to the current API key, and enumerates the returned fields (id, name, plan, site usage, site limit, dashboard URL). It is clearly distinct from siblings like get_stats or list_sites, though it never explicitly names those alternatives.

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 'the Hooky account this API key belongs to' implies usage context (identity/plan lookup for the authenticated key), but there is no explicit when-to-use or when-not-to-use guidance relative to siblings. An agent can infer it is the entry point for account metadata, but must reason about the boundary itself.

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 and openWorldHint=false, so safety is covered; the description goes further by enumerating the returned shape (enabled, active, source_url, instructions, knowledge sub-fields, monthly quota with used/limit). It also explains the meaningful semantics of source_url, including that Shopify and WooCommerce catalogs are discovered automatically. It stops short of describing failure modes or what happens when the plan lacks the feature.

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 definition is front-loaded with what the agent is and how it behaves, then moves to the returned fields. It is a single dense sentence with a long parenthetical, which is efficient but slightly hard to scan; every clause, including the catalog-discovery note, carries real 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 correctly compensates by listing the returned fields and the quota counters, which is exactly what an agent needs to interpret the response. For a single-parameter read tool this is close to complete, with only error and plan-gating behavior left 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?

There is a single required parameter, site_id, and the schema already documents it at 100% coverage including the pointer to list_sites. The description adds nothing about the identifier itself, so the schema does all the work and the baseline of 3 applies.

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

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

The description clearly identifies the resource as the site's AI agent and explains what that agent does (answers visitors from site knowledge, escalates to the team). It is specific enough to distinguish it from sibling reads like get_conversation or get_channel, though it never names those alternatives explicitly. The title's verb 'Read' supplies the action the prose leaves implicit.

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 only explicit usage guidance is the prerequisite 'paid plans only, see available', which is useful but is a plan gate rather than a when-to-use rule. It implies inspection of the agent's configuration and knowledge state, but never says when to call this versus update_ai_agent or how it relates to sibling read tools. Usage is inferable, not stated.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds value beyond that: the default page window (latest 50), the ordering (oldest first), and the exact payload fields returned (mrkdwn text, username, attachments, created_at). It does not cover edge behavior such as invalid ids or what happens when before/after reference a deleted message, but for a read tool this is solid added context.

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

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

Two sentences, front-loaded with the default result set and ordering, then the field payload, then pagination. The parenthetical field list is dense but every element is load-bearing; 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 no output schema, the description carries the burden of describing the return shape, and it does so by naming the returned fields and the 50-item default window. What is missing is modest: whether the feed includes all notification types, and error or empty-result behavior. Adequate for a four-parameter 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it frames before/after/around as a single cursor mechanism that pages through a chronological feed, and clarifies that the referenced id is a message id. That conceptual framing helps an agent choose the right cursor parameter rather than reading three unrelated integer filters.

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

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

The description states a concrete resource and result: the latest 50 notifications of a single site's channel, returned oldest first, with the fields included. It is clearly a read of one channel rather than a channel list, though it never names the sibling it is not (list_channels / search_channels), so the differentiation is implied by scope only.

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 when-to-use or when-not-to-use statement and no named alternative. What exists is implied usage: reading a channel's feed, and the note that before/after/around 'move through the feed' hints at the paging workflow without ever saying which to pick when.

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 readOnlyHint=true and openWorldHint=false, it discloses a genuinely non-obvious side effect: 'Reading marks nothing as read,' which matters because a read of a conversation could plausibly create a read receipt. It also states default ordering ('oldest first'), which annotations do not cover.

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

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

Two sentences, both front-loaded with the most important facts: what is returned first, then pagination semantics, then the no-read-receipt note. The parenthetical field list is compact and useful given there is no output schema; no sentence is wasted.

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

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

With no output schema, the description compensates well by enumerating returned fields, stating ordering, and clarifying the read side effect. Minor gaps remain: no mention of how many messages are returned or how before and after interact when combined.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the description's before/after wording largely restates the schema ('Return the messages after this message id'). The added value is only the intuitive threading framing, which is marginal, 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?

The description names a specific verb+resource (read one conversation) and even enumerates the returned fields (sender, author_name, body, locale, attachments), so the agent knows exactly what it gets. It does not explicitly contrast itself with the sibling list_conversations, which the agent must infer from the schema reference.

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 explains how to paginate through the thread: 'before goes back in the thread, after returns newer messages,' which tells the agent when to use each parameter. It stops short of stating when to prefer this tool over list_conversations or what happens if both windowing parameters are supplied.

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?

readOnlyHint=true already covers the safety profile, and the description goes beyond it by describing the returned shape (per-event aggregation plus the 20 most recent events), which matters because no output schema exists. Auth needs and rate limits are not mentioned, and the '20 most recent' cap is the only disclosed limit.

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 payload description is front-loaded in a single dense sentence, followed by a short scope clause. The parenthetical about Hooky.track is somewhat heavy but earns its place by explaining the data source; 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?

For a read-only reporting tool with no output schema, the description supplies the important missing piece: what the response contains. Remaining gaps are minor – ordering of events, pagination limits, and the exact default date window (30 days lives in the schema, not the description).

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 five parameters are already documented, giving a baseline of 3. The description adds one real semantic point – that omitting site_id returns all sites – but says nothing about how days interacts with from/to or how time_zone shifts the daily series.

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 resource precisely (event stats) and enumerates the payload: per-event count, total value, daily series, and the 20 most recent events. It does not name or contrast with any sibling, but the sibling list (sites, channels, conversations, agents) is far enough away that confusion is unlikely.

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 explaining where the data originates (Hooky.track on site or sent from a server), which tells an agent when numbers will exist. There is no explicit when-to-use/when-not guidance and no mention of alternates for time-series or per-site breakdowns.

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 and openWorldHint=false, and the description adds real context beyond them: channels are per-site notification feeds in Slack webhook format delivered to channel_url, and each result carries the last message. It omits ordering, pagination, and whether results span all sites or one site.

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

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

Two tight clauses with no filler, but the definitional preamble comes first and the operative verb "Lists" arrives late. Front-loading the action would improve scanability without adding 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?

For a parameterless, read-only list tool with no output schema, the description covers what a channel is, where messages come from, and that the last message is included. It is only slightly short on result-set scope (per-site vs all sites) and ordering.

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 is trivially complete and there is nothing for the description to disambiguate. Baseline of 4 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 concrete verb and resource ("Lists each channel with its last message") and defines what a channel is, which separates it from the singular get_channel. It never names search_channels as the alternative, so sibling differentiation is only partial.

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: use this to enumerate all channels rather than fetch one. There is no explicit when-to-use/when-not statement and no pointer to search_channels or get_channel for narrower lookups, leaving the agent to infer the routing.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, and the description adds a genuinely non-obvious side-effect guarantee: 'Reading marks nothing as read.' It also documents ordering (most recent first) and the meaning of 'unread' for the team, which go beyond the structured fields.

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

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

Content is front-loaded: what the call returns first, then the no-mark-as-read guarantee, then pagination. It is one dense run-on sentence-chain, but nearly every clause carries information and nothing is repeated wholesale.

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 compensates by enumerating returned fields (visitor name/email, source page, last message preview, unread flag) and ordering. Combined with the read-side-effect note, an agent has enough to call it correctly; only the site_id scoping 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?

Schema coverage is 100%, so all three parameters are already documented; the baseline is 3. The description echoes the closed and cursor semantics ('Pass next_cursor as cursor') and never mentions site_id, so it adds little meaning beyond the schema.

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

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

The description opens with a concrete resource framing ('The live chat inbox: ongoing conversations with visitors') and adds scope details (most recent first, closed vs ongoing). It is separable from get_conversation and list_channels without opening a schema, though it never names a sibling explicitly.

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

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

It gives operational guidance for pagination ('Pass next_cursor as cursor for the next page') and for the closed flag, but never states when to use this list versus get_conversation for a single thread or search_channels. Usage is implied by the 'inbox' framing rather than stated as a decision rule.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description still adds real context: it flags secret_key as server-side only and never for front-end code, and explains that install.script_tag must be pasted once before </body> in the shared layout. It does not address whether all sites are returned, ordering, or auth requirements, but the sensitive-field disclosure is genuinely valuable.

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 resource is front-loaded in the first clause, and every subsequent clause describes a returned field or a usage caveat, so nothing is filler. The single sentence is long and heavily nested with parentheticals, which slightly hurts scanability for an agent parsing field names.

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, no parameters, and a read-only annotation, the description carries the return-value burden and does it well by enumerating id, name, domains, public_key, appearance subfields, channel_url, secret_key, and the install snippet. Gaps are minor: no statement that all sites are returned without pagination, and no indication of the shape of nested fields beyond appearance.

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; there are no arguments whose meaning the description could clarify. The field descriptions it does provide concern the response, not the input, so they are assessed under other dimensions.

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 opens with 'The account's websites,' which clearly identifies the resource being listed, and the tool name plus readOnly annotation make the listing action unambiguous. It is trivially distinguishable from create_site and update_site by name, but it never explicitly frames itself as a retrieval operation nor names any sibling.

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: an agent infers it should call this to obtain site ids, public keys, or the install script tag. There is one useful routing hint ('see get_channel') for the channel_url field, but no statement of when to prefer this over alternatives or any preconditions.

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: it discloses that the message reaches a REAL human immediately (in-chat or by email), is signed with the API key creator's name, marks the conversation as read, and is capped at 5,000 characters. These are consequential, non-obvious side effects for a mutation tool that openWorldHint=true only hints at.

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

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

Front-loads the action in the first sentence, then layers constraints (visitor impact, signing, read-marking, approval workflow, language, length). Dense but nearly every clause carries operational value; the signing-parenthetical is the only slightly expendable detail.

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 that is human-visible and irreversible (no idempotency, no undo stated), it covers the confirmation workflow, delivery channel, authorship, language, and length limit well. The main gap is that no output schema exists and the description says nothing about what is returned (e.g., a message id) or failure behavior.

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 body and conversation_id are already documented; baseline would be 3. The description adds real value on top: the 5,000-character limit for body and the language/locale guidance for the reply text, neither of which is in 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?

The description opens with a specific verb and resource: 'Sends a reply in a conversation.' No sibling tool (create_site, get_conversation, update_ai_agent, etc.) sends a message to a visitor, so the operation is unambiguously distinct from the read/update tools in the sibling list.

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 an explicit action protocol: show the reply to the user and wait for their OK, unless they asked the agent to answer on its own. That is a clear when-to-act/when-to-confirm rule. It doesn't name any alternative tool, but no sibling competes for this action, so the omission is minor.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is covered; the description adds genuinely new behavior: case- and accent-insensitive matching, a fixed 30-result page, and newest-first ordering. It omits any note on result fields or limits beyond pagination, but the added behavioral detail is well above the annotation baseline.

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 with no filler: scope first, then pagination mechanics. Every clause carries usable information.

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

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

For a three-parameter read-only search with no output schema, the description covers matching semantics, ordering, page size, and the pagination loop, which is everything an agent needs to call it and page through results correctly.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning beyond the schema by clarifying that q matches ALL words (AND semantics) rather than any, and that before should be taken from the last result's message id. That is practical invocation guidance 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 ("Searches every channel") plus the matching scope ("all the words of q, ignoring case and accents"), which separates it from list_channels and get_channel 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?

Clear operating context: search spans all channels unless site_id narrows it, and continuation requires passing the last result's message id as before. It does not explicitly name when to prefer list_channels or get_channel instead, so it stops short of full when/when-not routing.

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

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

With idempotentHint and destructiveHint already supplied, the description still adds real behavior: a new source_url is re-read within a minute and nightly, refresh: true forces an immediate read, and the call fails with plan_required on the free plan. It does not describe what happens to prior instructions when omitted, 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?

Three tight sentences: purpose first, then the refresh timing, then the failure mode. Every clause carries information an agent needs, 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?

No output schema exists, yet the description discloses the knowledge.refreshing state to expect and the plan_required error, and all five parameters are fully documented in the schema. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns credit by explaining the timing semantics of refresh relative to the automatic re-read within a minute and the nightly refresh. That adds meaning beyond the schema's terse 'Read source_url again now.'

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: turning a website's AI agent on or off and setting what knowledge it uses. This clearly separates it from read-only siblings like get_ai_agent and from create_site, so an agent can pick it without opening the schema.

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

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

Usage is implied rather than stated: the description covers configuration and refresh behavior, and notes the free-plan failure, but never explicitly says to use get_ai_agent for reads or update_site for site settings. The agent must infer the routing from the verb.

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, so the description's job is to explain why. It does exactly that: domains overwrites the entire allow-list and 'the bubble stops loading on any address left out' — a concrete, non-obvious failure mode an agent would not infer from the schema. Still silent on whether omitted fields are left unchanged and on 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?

One dense but well-ordered sentence: the field list first, then the domains/add_domains contrast and its warning. No filler, and the highest-risk information is placed where the eye lands.

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 an 8-param mutation tool with no output schema, the definition covers the one parameter pair that can cause real damage. The remaining gap is partial-update semantics: nothing states that unspecified fields are preserved, which matters for an idempotent-but-destructive update.

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

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

Schema coverage is 100%, so baseline is 3; the description earns a step up by disambiguating the two easily-confused domain parameters and spelling out the operational consequence of the replace option. Nothing is added for position, theme, or greeting_enabled 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?

States a specific verb ('Changes') and resource ('a website'), then enumerates the mutable fields (name, color, position, theme, greeting_enabled). Combined with the sibling list, which is dominated by get_/list_ readers and a separate create_site, an agent can place this immediately as the mutation path.

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 gives explicit param-level decision guidance: add_domains appends, domains replaces everything. That is a genuine 'use A vs B' rule. It stops short of tool-level guidance (when to update vs recreate via create_site, or required permissions), so not 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 destructiveHint=true and idempotentHint=true, and the description goes further by disclosing that the upload replaces the previous file, that remove:true deletes it, the 5 MB / 2,000-product ceilings, and the empty_file failure mode. The main gap is that it doesn't say what a successful response contains or what happens to a partially valid file.

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, then limits, replacement semantics, and error code — all sentences earn their place with no filler. It is dense to the point of being semicolon-chained, which slightly hurts scanability.

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 5-parameter tool with no output schema, the description covers formats, limits, overwrite behavior, deletion, and one error code — nearly everything an agent needs. Missing details are the success return value and behavior on malformed rows.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: content takes CSV with comma/semicolon/tab delimiters, content_base64 takes .xlsx, and the first row must be column headers with names like name/price/stock/url in any language. That maps parameters to formats in a way the schema does not.

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 ('Gives a website's AI agent a products file') and immediately scopes it as replacing the online catalog (Shopify, WooCommerce). No sibling tool does anything similar, so an agent can distinguish it from list_sites/update_site 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?

Implies the when-to-use case by saying the file 'replaces the catalog found online', which is a useful trigger condition. However, it gives no explicit when-not guidance, no mention of how this interacts with channel/catalog siblings, and no prerequisites (e.g., whether the site must already exist).

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