Kooga

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

With annotations present, the description still adds real value: it says the change applies from the next check onward, that past answers are not re-read, that duplicates by name/site are rejected, and that the call runs immediately as the acting person. That's substantive side-effect and authorization context beyond readOnly/destructive hints; only the return/error shape is left implicit (though an output schema 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?

Front-loaded with the action and the fields it affects, then the timing and dedupe rules. It runs a little long with the closing 'A change inside Kooga' line, but every sentence carries behavioral information rather than restating 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?

For a mutating tool with four parameters, a dedupe rule, and a self-exclusion rule, the description covers timing of effect, uniqueness constraints, and where to read the result. An output schema exists, so return values need not be explained; only workspace scoping is left to the schema alone.

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

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

Schema description coverage is 100%, so the schema already defines all four parameters, and the description adds only conceptual framing (site, alternate engine names, self-exclusion). The workspaceId parameter is not mentioned at all, so the description does not fully relieve the agent of reading 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 (add a competitor) and names the concrete fields it captures — name, site, aliases. It also distinguishes the tool from readCompetitors by stating that listing is done via readOptions with kind competitors, so an agent can tell which one to call.

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

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

The description makes the use case and constraints explicit: dedupe by name or site, the brand cannot be its own competitor, and the resulting list is read via readOptions. It doesn't spell out explicit when-not-to-use or contrast against any other sibling beyond that, 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?

With annotations covering the mutation/safety profile, the description still adds real value: the prompt is only used from the next scheduled check ('nothing runs now'), the plan holds a fixed number of prompts, and a duplicate prompt is not re-added. The trailing line about running 'as the person' is confusing and adds little. Minor tension between 'already tracked is not added again' and idempotentHint=false, but this reads as dedup-with-error rather than a contradiction.

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 is front-loaded, but the prose is a dense run-on with parenthetical asides, and the closing sentence ('A change inside Kooga: it runs at once, as the person.') is opaque filler that does not earn its place.

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

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

For a 5-parameter mutation with an output schema and annotations, the description covers timing, plan limits, deduplication, category semantics, and topic discovery. About the only gap is that it doesn't say what happens on a duplicate (error vs silent no-op), which an agent would want to know.

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 80%, so most parameters are already documented. The description's key contribution is explaining the category enum, which the schema leaves as bare values, including the default and the plan-consumption difference between 'topic' and the brand categories. It also reinforces the expected phrasing for 'text'.

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 clause names a specific verb+resource ('Add a question to the ones AI Visibility asks the engines on every check') and clarifies the expected phrasing, which is genuinely distinguishable from siblings like addCompetitor or trackKeyword. The category taxonomy further scopes what kind of prompt is being added, though the sentence structure wanders before the point lands.

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 explains when each category applies and which ones consume the plan's brand-prompt allowance ('topic' does not name the brand; 'brand' and 'comparison' count against the plan). It also points to readOptions with kind promptTopics to discover existing topics. It never states when NOT to use this tool versus addCompetitor, but the category guidance covers most selection decisions.

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 explains the confirmation flow: external effects such as publishing, sending, live-store changes, or paid checks require the person to confirm first. It also explains that the first call may return a question plus confirmToken, and that the token must only be used after the person confirms.

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 purpose is front-loaded, but the description is a dense paragraph with awkward phrasing such as 'the same way as that change on its own' and 'where the app can show the question it does.' The information is valuable, but the structure could be much easier to parse.

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, open-world action with no output schema, the description covers the critical confirmation path and external side effects. It does not describe the successful return value after approval, but the essential invocation and confirmation semantics are present.

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 parameter descriptions already carry baseline meaning. The tool description adds useful context by identifying readWaitingItems as the source of actionId and by explaining the confirmToken confirmation 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?

The description states a specific verb and resource: approve one task waiting on Tasks, and clarifies that Kooga carries out the proposed action. It also distinguishes approvals from questions or steps to do in Kooga, so an agent can tell what this tool is for.

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

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

It gives a clear prerequisite by pointing to readWaitingItems for the actionId and explicitly excludes questions and manual steps from approval. It does not name other sibling alternatives for those excluded item types, but the when-to-use and when-not-to-use conditions are clear.

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

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

The description adds useful context beyond the annotations: the result is only a draft, nothing reaches the site until published, it runs immediately as the person, and it consumes one article from the workspace's plan. These details are meaningful for a mutation tool, though the wording about running 'as the person' is somewhat vague.

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 main purpose is front-loaded, and the description is short. However, the second paragraph is phrased in awkward fragments ('A change inside Kooga: it runs at once, as the person') that reduce clarity rather than adding crisp 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?

Given the full schema coverage and existing output schema, the description provides enough context about the tool's draft-only behavior, immediate execution, and plan usage. It is mostly complete for an agent to invoke it correctly, with only minor ambiguity around execution semantics.

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 parameters are already well documented. The description reinforces the meaning of topic and evidence but does not add syntax, format, or constraint details beyond what the schema provides.

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: writing a draft article on a buyer topic where the brand is invisible. It distinguishes the output as a draft in Kooga rather than a published article, though it does not explicitly differentiate itself from siblings like generateArticle or publishArticle.

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

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

It gives a clear condition for use: a topic the brand is absent from, supported by evidence. However, it does not name when not to use it or explicitly point to alternatives such as generateArticle or publishArticle.

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, destructiveHint=false, so the bar is lower; the description still adds real behavior: only subscribed contacts are ever included, no one is mailed, the operation executes immediately, and the response returns the id plus current subscriber count. It doesn't disclose what happens on duplicate names or whether the segment is later editable.

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 verb and resource, then a compact rule-by-rule enumeration that matches the schema's anyOf branches; nearly every clause carries information. The closing line about running at once 'as the person' is terse to the point of being opaque, the one spot that doesn't fully earn its phrasing.

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 with nested rule variants, the description covers the risky/ambiguous part (rule semantics and match logic), the side-effect profile (no mailings, subscribed-only), and the return shape, so an agent can call it correctly without reading further. An output schema exists, so return values need no more detail.

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 40%, but the description does the heavy lifting for the complex parameter: every rule field/operator pair is explained semantically (source origin, before/after on a day, gte/lte on counts and spend with currency noted, contains/excludes for products and searched terms), and match 'all' vs 'any' is disambiguated. That adds meaning well beyond the anyOf structure.

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 and resource ('Save a segment: subscribers that match rules') with the scope stated up front, and it explicitly distinguishes itself from the read sibling ('readSegments lists the ones there are'). An agent knows immediately this creates a stored segment rather than listing one.

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 makes clear this is for persisting a reusable group and that readSegments is the way to see existing ones, and it pre-empts the sending interpretation with 'Nobody is mailed.' It gives downstream consumers (previewSend, draftCampaign) but stops short of explicit when-not conditions such as how to handle an already-existing equivalent segment.

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 destructiveHint=true by disclosing irreversibility and the full two-phase confirmation protocol after an out-of-band change, including that the first call mutates nothing and returns a question plus confirmToken. That is exactly the behavioral context annotations cannot express.

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 constraint (only unsent campaigns) and the undo warning early. The confirmation paragraph is dense but earns its space; a couple of clauses about where the app can show the question are slightly indirect but necessary for correct invocation.

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 explains the notable return shape (a question to relay verbatim plus a confirmToken). For a destructive, non-idempotent tool with confirmation gating, an agent has everything needed to call it correctly and safely.

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; the description still adds value by pointing to readCampaigns as the source of broadcastId and by warning that names are not unique, explaining when campaignName is used. The confirmToken usage rule is reinforced beyond the schema wording.

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 (delete) plus resource (campaign), with the scope narrowed to drafts and scheduled campaigns and the sent case explicitly excluded. It also names updateCampaign as the non-delete alternative, so the agent can separate it from the other campaign-mutating 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?

States when to use it (draft or scheduled campaign, send called off), when not to (a sent campaign cannot be deleted), the alternative (updateCampaign), and the id source (readCampaigns). It even gives a disambiguation rule when several campaigns match a spoken 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?

Adds meaningful behavior beyond annotations: it runs immediately, acts as the person, and the recorded reason steers agents not to raise the same item again soon. Annotations already cover destructiveness and idempotency, so this is strong supplemental 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?

Front-loads the action and follows with the reason options, the downstream effect, and how to obtain the actionId. Every sentence contributes useful context 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?

Complete enough for a destructive mutation: it identifies the task source, immediate execution, acting identity, and future suppression effect. It could say more about reversibility or undo, but annotations and the sibling undoAction help cover that.

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

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

Schema coverage is 100%, so the schema already documents actionId, reason, and workspaceId. The description mainly repeats the reason enum values and points to readWaitingItems for actionId, without adding much semantic depth beyond the schema.

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

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

States a specific verb and resource: declining one waiting task on Tasks. It clearly distinguishes the action from readWaitingItems, which lists the cards, and implies the opposite of approveItem.

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

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

Explains that this is for declining one waiting task and that readWaitingItems supplies the actionId. It gives clear usage context but does not explicitly compare against approveItem or undoAction.

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 a non-destructive, non-idempotent write, and the description adds genuinely useful context: nothing is sent, a human reviews it in Email → Campaigns, and every call creates a new campaign rather than mutating one. It stops short on failure behaviour and the closing line 'it runs at once, as the person' is opaque rather than clarifying.

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 purpose and the draft-safety guarantee lead, and the alternatives come after. The middle section is dense and clause-heavy ('Or lay it out yourself in `blocks`, with its `subject`: when the person describes...'), costing some readability, but nearly 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?

For an 11-parameter tool with a deep block union, an output schema, and full schema coverage, the description covers lifecycle, preconditions, mode selection, A/B defaults, and sibling routing. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so per-parameter text is already handled; the description's added value is cross-parameter semantics — productIds rendered as one grid vs. authoring blocks, subject being required with blocks but auto-written otherwise, brief demoted to context when blocks are given, and abTest=false skipping the test. Those interactions are not obvious from the schema alone.

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 precise scope: write a campaign for a segment and leave it as a DRAFT, nothing sent. It explicitly separates itself from siblings (updateCampaign for changes, deleteCampaign for unwanted ones, readCampaign for viewing the body), so an agent can pick the right tool without reading 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 explicit routing instructions: preview the audience first, use updateCampaign with broadcastId to modify an existing draft, deleteCampaign to discard, and each call creates a new campaign. It also states a precondition ('Only for a workspace with subscribed email contacts'), covering when-not usage.

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?

Well beyond the annotations: the description says existing steps are replaced, explains why an active flow is refused (shoppers part-way through would see changed steps), distinguishes personal vs. pre-written emails, and notes the change runs at once inside Kooga. The one gap is that it doesn't say what happens to the previous emails' content or whether drafts are recoverable, though destructiveHint already flags the risk.

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 and constraints, but the sentences are long, run-on, and stack parentheticals (the wait-time clause, the personal/written clause) that the schema already covers. It is dense rather than wasteful, but readability suffers.

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, annotations carry the safety profile (destructive, non-idempotent), and the description fills the remaining gaps: prerequisites, the flow-off requirement, the enableFlow hand-off, and the per-flow default behavior. An agent has everything it needs 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 description coverage is 100%, so the baseline is 3; the description still adds value by restating the personal/written default per flow kind, the auto-added 'purchased' stop condition, and the wait-time semantics. It doesn't add anything new about workspaceId or couponPct beyond the schema, so not a 5.

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 and resource ('Write the emails of one automated flow and save them with the flow off, replacing the steps it had') and explicitly bounds the scope (up to eight emails, wait times, briefs, stopping conditions). It distinguishes itself from enableFlow and updateFlowStep by making clear it replaces the whole step list rather than toggling or editing one 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?

Usage conditions are explicit: the flow must be off, an already-on flow is refused, and turning it on is the job of enableFlow, 'which asks the person'. It also states the prerequisites (workspace with subscribed email contacts) and the fallback ('Without a store, only the welcome flow').

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 destructive/openWorld/non-idempotent, but the description adds the crucial behavior those flags cannot: the two-step confirmation protocol, where a first call mutates nothing and returns a question plus confirmToken to be replayed only after human assent. It also discloses the real-world effect (emails send automatically) and that merchant sign-off happens once per flow.

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 eligibility, then the confirmation handshake — a sensible order. Some phrasing is roundabout ('the people it is for, so the merchant always says yes first, once per flow') and could be tightened, but no sentence is dead weight.

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, open-world mutation with no output schema, the definition covers what an agent needs: eligibility gates, the side effect outside the product, and exactly what the first and second calls return/require. Nothing material is 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by constraining which kind values are legal in a given context (no store → welcome only) and by reinforcing that confirmToken is never to be invented. The confirmToken replay rule is partly duplicated from the schema, keeping it out of the top band.

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: 'Switch on an automated email flow.' It is clearly distinguished from draftFlow (create), readFlows (read), and updateFlowStep (edit a step) — this is the activation step for an existing 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?

Explicit preconditions and exclusions: flow must be off, business must have the audience, 'without a store, only the welcome flow', and only for workspaces with subscribed email contacts. An agent can decide eligibility without further 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 and closed-world, so the description correctly spends its words elsewhere: newest-first ordering, the constraint that only contacts with an address appear, and a prompt-injection caveat about externally-written data. That caveat is genuinely additive for an agent consuming untrusted fields, though return shape and rate limits are not discussed.

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

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

Front-loaded with purpose and scope, followed by sibling routing, filter advice and pagination semantics before the safety note. Dense but each sentence carries distinct information; the filter clause lists are slightly packed but not wasteful.

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 field detail is unnecessary, and annotations cover the safety profile. The description supplies what structured data cannot: ordering, an exclusion rule for address-less contacts, and an untrusted-data warning. Only minor operational details (limits on the 25 max, workspace resolution) are left implicit.

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

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

Schema coverage is 83% and the enum descriptions for status/source are already thorough, so the baseline is 3. The description adds the pagination contract beyond the schema — `total` is the match count and `next` is the page cursor — which clarifies how cursor and limit 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 resource and scope ("The workspace's email contacts, newest first") plus the three filter axes, and explicitly names the two siblings it is not (readContact, previewSend). An agent can pick this over related tools 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?

"For one contact in full ... use readContact; for how many a campaign would reach use previewSend" gives explicit alternatives, and "Narrow with search, status or source rather than paging through everyone" states the preferred usage pattern over raw pagination.

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 annotations, the description adds important context: execution is immediate and runs 'as the person', the output is a non-public draft, and it consumes one article from the workspace's plan. It does not cover error behavior or rate limits, but adds substantial behavioral detail.

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 short and front-loaded with the core purpose. The later sentences are slightly fragmented but each adds relevant behavioral detail without excess verbosity.

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?

Given the presence of an output schema and fully described parameters, the description covers the key behavioral aspects an agent needs: draft state, immediate execution, and plan usage. It could mention failure modes or rate limits, but is largely complete.

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

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

Schema coverage is 100% and parameter descriptions are rich, so the schema carries the semantic load. The description adds little beyond the schema, only reaffirming that a topic is required and that the tool uses a plan article.

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 (research and draft) and resource (new SEO article) and includes the scope that the result is a draft. It implicitly distinguishes from publishArticle and refreshArticle but does not explicitly name or contrast with 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 implies usage by explaining the result is a draft and that publishing is a separate step, but does not specify when to use this tool versus alternatives like researchKeywords or refreshArticle. No explicit when-not guidance is provided.

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 safety is covered. The description adds real behavioral detail beyond that: what an empty prefix returns (top-level folders, including merchant-created ones) and what each listed file carries (key, file name, size). It stops short of stating pagination or ordering, 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, front-loaded with what is listed, then the prefix behavior, then sibling routing. No restated field names and 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 present, return values need not be spelled out, yet the description still previews the per-file fields. Combined with full schema coverage and complete annotations, 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 already documents both parameters, so the baseline is 3. The description earns above baseline by explaining the meaning of an empty prefix versus a folder prefix and the consequence for the returned shape — semantics the schema only gestures at with an example.

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 statement ('The workspace's uploaded documents and folders') and then explains the two listing modes. It names the sibling tools (searchDocuments, readDocument) it is not, so an agent can distinguish 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?

Explicitly routes the agent: use searchDocuments for document content and readDocument with a key to read one in full. The prefix semantics ('a folder such as contract/ lists its files') tell the agent exactly which invocation to use for which intent.

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 mark it as read-only, idempotent, non-destructive, and closed-world. The description adds meaningful context beyond that: ownership/admin filtering, connection-scoped visibility, and the exact fields returned for each workspace.

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

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

The description is front-loaded with purpose and usage guidance, followed by return details and scope. Every sentence contributes useful information without unnecessary 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?

Given zero parameters, rich annotations, and an output schema, the description covers purpose, invocation guidance, return fields, and visibility scope. An agent has everything needed to decide whether and how to call it.

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

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

The tool has zero parameters, so the baseline is 4. The description mentions the returned id is passed as workspaceId elsewhere, but there are no input parameters to document.

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 states a specific verb and resource: 'List the Kooga workspaces this connection reaches.' It also clarifies the returned id's purpose as workspaceId, making the tool's role distinct from sibling read tools.

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 use cases ('when the person names a shop or a site, or when a tool says a workspace is needed') and an explicit exclusion ('a connection that reaches one workspace never needs it'). This leaves little ambiguity about when to invoke 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?

Beyond the read-only and idempotent annotations, the description explains that the tool breaks down reach by exclusion reason: suppressed, unsubscribed, recently mailed, or over today's limit. That adds useful behavioral context about what the preview reports, though it does not discuss auth or rate limits.

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, no wasted words. The core purpose is front-loaded, and the prerequisite and workflow instruction follow compactly.

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 preview tool with a full input schema, an output schema, and clear annotations, the description supplies everything an agent needs: what is computed, why exclusions occur, when to use it, and the workspace prerequisite. Return-value details can be left to the 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?

Schema description coverage is 100%, so both segmentKey and workspaceId are already documented in the schema. The description refers to 'this segment' but does not add parameter syntax, format, or examples beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: calculating how many contacts a campaign would reach for a segment and why others would be excluded. It is clearly a preview/reach-count operation, distinguishable from siblings such as sendTestCampaign or scheduleCampaign.

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 workflow guidance: 'Always do this before proposing a send.' It also states a prerequisite constraint: only for a workspace with subscribed email contacts. It does not name alternative tools, but the when-to-use context is strong.

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 the two-phase confirmation protocol: the first call changes nothing and returns a question plus confirmToken, and the second call must reuse that token. It also surfaces the quota cost (one manual check from the monthly allowance) and the external side effect, all consistent with destructiveHint=true, idempotentHint=false, and openWorldHint=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?

Purpose and preconditions are front-loaded in the first two paragraphs, and the confirmation mechanics follow in logical order. It loses a point for restating the quota cost twice, once as 'one manual check from the monthly allowance' and again as 'one visibility check from the workspace's plan.'

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 takes on the burden and does explain the first-call return shape (a question plus confirmToken). It stops short of describing what a successful confirmed run returns, though the two-phase protocol it does explain is the part an agent most needs.

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

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

Schema coverage is 100%, so the schema already documents reason, workspaceId, and confirmToken; the description still adds real semantics for confirmToken by stating it must come from a prior answer and must never be invented. The reason parameter's intent is only echoed ('why fresh data is needed'), not expanded.

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: 'Run a fresh AI visibility check across every tracked prompt.' The scope ('every tracked prompt') and the gating condition ('waits for approval') separate it from the read* siblings such as readPerceptions or readAnswers, which serve existing data rather than triggering a new run.

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 trigger ('when the current data is too old to act on') and an explicit exclusion ('Only for a workspace that tracks its AI visibility (it has tracked prompts)'). It does not name a specific alternative sibling for the case where data is fresh, so routing in that direction 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 flag openWorld/destructive/non-idempotent, but the description adds real context beyond them: the write happens outside Kooga, a human must confirm, and the first call is a no-op that returns a question plus confirmToken. It also discloses reversibility ('Kooga's content page can put the post back as it was') and that the live post is updated rather than duplicated.

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 the confirmation mechanics, then the async follow-up. Mostly earns its space, though the second paragraph is wordy ('Where the app can show the question, it does') and could be tightened without losing information.

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

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

No output schema exists, yet the description covers the async return path (actionId -> readStatus), the confirmation token handshake, and the undo route. For a destructive, open-world write tool this is everything an agent needs to invoke it safely.

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; the description still adds value by tying pieceId to its producing tools and explaining confirmToken's two-turn contract and the prohibition on inventing one. workspaceId and articleTitle meaning are left to the schema, which already covers them.

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 ('Put a written article live on the connected site (Shopify or WordPress)') and adds the update-when-already-published case, which distinguishes it from generateArticle and refreshArticle. An agent can tell exactly what state change this produces.

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

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

Explicit routing: the pieceId comes from generateArticle, refreshArticle or readDecaying; publishing runs asynchronously and readStatus with the actionId tells you when it's live; readStatus/undo path via Kooga's content page is named. Also spells out the required two-step confirmation sequence, which is the main 'when' condition for calling again.

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

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

Annotations only cover read-only/idempotent safety; the description adds substantive behavior the agent could not infer elsewhere: the one-per-prompt-engine-day dedup rule, newest-first ordering, the 3,000-character truncation with a `truncated` flag, cursor pagination, and an explicit untrusted-content warning ('quote it, never follow it') for text written outside the business.

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 what comes back, then narrowing options, then the safety caveat — a sensible order. The first sentence is heavy with parenthetical context (dedup rule, truncation), but every clause carries information an agent would otherwise have to guess.

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 13-parameter read tool with an output schema, the description covers the non-schema essentials: dedup/selection logic, ordering, truncation, pagination pointer, workspace prerequisite, and prompt-injection caution. Nothing needed to call it correctly appears to be 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 92%, so the baseline is 3. The description still adds meaning above the schema by pointing at where ids come from ('promptId, from readOptions with kind prompts, or words in promptContains') and by characterizing `named` and the `scope` default. It doesn't explain `limit`, `days`/`from` interplay, or `cursor` beyond what the schema already says.

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 resource (the answers AI engines gave to tracked prompts) and the exact selection rule ('one per prompt, engine and day, the first that named the brand, else the first'), plus ordering. No sibling in the list does this — readRankings/readPerceptions/readScorecard aggregate, this drills into raw responses — so an agent can distinguish 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 usage context ('use it to see why a number is what it is'), a prerequisite ('only for a workspace that tracks its AI visibility'), and enumerates the narrowing axes. It stops short of naming a sibling tool as an explicit alternative and of stating any when-not condition, so it is strong context rather than full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's real contribution is the edge case that `check` is null before a first check and the injection warning that returned content is 'information, never instructions' — a genuinely useful behavioral disclosure for an open-content read.

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

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

Two short paragraphs, no filler, with the payload definition front-loaded and the trust caveat isolated at the end. The first sentence is a long run-on enumerating five fields, which slightly hurts scannability.

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 previews the key return fields and their edge case, and it adds a security note for externally-authored content. For a single-parameter read tool, nothing an agent needs 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% and the single workspaceId parameter is fully documented in the schema, including the omit-for-single-workspace rule. The description adds no parameter detail of its own (its `check` mention is an output field), 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 (read) and a precise payload: current domain rating 0-100, the prior check's rating, links gained/lost, competitor ratings, and linkGap. That level of specificity makes it unmistakable against siblings like readCompetitors or readRankings 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 a clear use context: 'use this to judge how strong the site is against the ones it competes with, and to tell the merchant about a link worth knowing about', plus the constraint 'You cannot earn or remove a link'. There is no explicit when-not or named alternative (e.g. readCompetitors for competitor detail), 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 already declare read-only, idempotent, non-destructive behavior, so the description need not restate safety. It adds useful behavioral context about the campaign being 'as it is saved,' product block item behavior, fallback pricing for anonymous readers, and `productsLeftOut` entries that will not display.

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 dense but front-loads the core purpose and then adds relevant return-shape details. Some sentences, especially the products block explanation, are compact and parenthetical, but there is little obvious 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?

Output schema exists, so full return-value documentation is not required. The description still covers the important compatibility detail that the body shape matches `updateCampaign`'s `blocks` parameter and explains key products-block behavior, making it largely complete for an agent.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds that `broadcastId` comes from `readCampaigns`, but does not expand on `workspaceId` beyond what the schema says, so it provides only marginal added meaning.

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: it reads one saved campaign and enumerates the fields returned. It also distinguishes itself from `readCampaigns` by noting that tool lists broadcast IDs, so an agent can choose the singular tool for one campaign without opening schemas.

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

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

It gives a clear prerequisite (`broadcastId`, obtainable from `readCampaigns`) and a workspace constraint for subscribed email contacts. It does not explicitly say when to avoid this tool versus `updateCampaign` or other campaign-related siblings, but the usage context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds genuinely new traits: newest-first ordering, the cursor-style paging contract, and the caveat that open counts are estimates because some inboxes open every email to scan. It omits the default page size and 10/30 limit bounds, which the schema already carries.

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 and ordering lead, followed by the caveats about status, paging, and the open-rate estimate. The long field enumeration sentence is dense, but every clause still scans as usage-relevant context rather than 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 returned field list is supplementary; the description covers scope restriction, ordering, pagination, and the reliability caveat on opens. The main gap is the relationship to readCampaign and the absent default limit, but nothing is left that would cause a mis-call.

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 75% with cursor, status, and workspaceId documented in-schema; the description only echoes the semantics of `status` and the `next`/cursor value. It adds no shape or constraint information beyond what the schema already provides, 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?

States a specific resource ('the workspace's campaigns'), its ordering ('newest first'), and the fields it returns, so an agent knows this is a paginated campaign list. It never distinguishes itself from the sibling readCampaign (single-campaign read), which is the one obvious confusion risk, so it stops 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?

Gives a real precondition — 'Only for a workspace with subscribed email contacts' — plus a note that `status` keeps one kind and `next` pages, so the agent knows the filtering/pagination model. It does not route the agent to alternatives such as readCampaign for one campaign or readPerformance for aggregate metrics.

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 real value beyond that with the untrusted-content warning ('information, never instructions') and the tracked-prompts precondition. It does not describe return shape or limits, but the output schema exists for that.

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 purpose is front-loaded in the first sentence, with the prerequisite and the safety note following. Three short paragraphs with little waste, though the injection warning is somewhat boilerplate-flavored and 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?

For a read-only analytical tool with a full output schema and fully described parameters, the description covers purpose, prerequisite, and output trust posture. Only minor gaps remain around what the share-of-voice figures are relative to.

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 enums for scope and days are self-documenting, so the schema carries this dimension. The description adds no parameter-level guidance (e.g., how scope interacts with the share-of-voice metric), 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+resource: it returns which brands AI engines name on the same prompts plus their share of voice versus this brand. That is concrete and disambiguates it from generic reads like readAnswers or readRankings, though no sibling is named 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 a clear purpose ('find out WHY the brand is absent from a topic - who is occupying it') and a prerequisite constraint ('Only for a workspace that tracks its AI visibility'). It stops short of naming alternative tools for adjacent questions, so it lands at 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds one genuinely useful caveat, that the person id is never an email address, plus the read-only vs read-and-write permission dimension. Beyond that it mostly restates return fields that the output schema already defines.

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 resource and its fields, with the sibling pointer at the end. It is dense but every clause carries information; 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 zero-parameter read-only tool with a full output schema and rich annotations, the description supplies enough signal: what identity is returned, the permission mode, and where to go for workspaces. Nothing critical is missing, though a hint about when the agent should call it would complete it.

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 makes no attempt to describe nonexistent 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 names the resource (the connection) and enumerates what it exposes: acting person id, app, permission mode, and workspace count. That is specific enough that an agent knows this reports the current connection's identity and scope rather than listing workspaces. It stops short of a single crisp verb-plus-resource statement, so it's clear but slightly indirect.

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 routes one case away from this tool: 'Use listWorkspaces for the workspaces themselves.' That implies readConnection is for identity/permission checks, but there's no explicit statement of when to reach for it (e.g., before a write to confirm read-write scope) and no coverage of the many other read* 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?

Adds substantial context beyond the readOnly/idempotent annotations: partial-failure semantics ('a part that cannot be read says so and the rest still answers') and an explicit warning that returned content is externally authored and must be treated as data, not instructions. That injection warning is exactly the kind of behavior annotations cannot convey.

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 is returned, then the optional sections, then the caveats. The first sentence carries a long appositive list which is a little dense, but the paragraph break for the untrusted-content note is well-judged and nothing is redundant.

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 restate return shapes, and it correctly focuses on scope, optional sections, partial-failure behavior, and the trust boundary. 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: `sections` values are explained ('consent' = full consent history, 'messages' = latest emails and open status) rather than repeating the schema's terse 'More than the contact and its orders'. contactId and workspaceId usage are both reinforced.

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 ('One contact in full, by the contactId') and enumerates exactly what is returned (address, name, consent, source, conversation questions, orders). It also ties itself to the sibling tool that produces the identifier (findContacts), so an agent can place it precisely.

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 on the entry path: get contactId from findContacts, and opt into more detail via the `sections` array with 'consent' and 'messages' spelled out. It does not explicitly contrast with updateContact or other read tools, but the read scope is unambiguous.

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

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

Beyond the readOnly/idempotent annotations, it discloses the aggregation-only privacy behavior and the store-connected precondition, which are the two things most likely to cause a wrong or failing call. Return shape is left to the output 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?

Two short sentences with the core scope front-loaded and the precondition second; nothing is redundant or 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 full schema coverage, annotations, and an output schema, the description covers the essential prerequisites and privacy semantics. A note on behavior when no store is connected would make it complete.

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

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

Schema description coverage is 100% and the schema already explains the from/to pairing, the two-year cap, and the days enum, so the description adds no parameter detail. Baseline 3 applies; the phrase 'for a period' only loosely gestures at from/to/days.

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 — new versus returning customers for a period plus top locations — and rules out individual-level data, which separates it from findContacts/readContact. It does not name a closest sibling outright, but the scope is unambiguous.

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

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

Gives an explicit precondition (a workspace with a store connected) and points the agent to listWorkspaces to check store status, which is real routing guidance. It stops short of stating what to use instead when no store is connected or when per-customer data is needed.

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, closed-world, non-destructive, so the safety profile is covered. The description adds the sort order, which is real behavioral value, but says nothing about the truncation quirk or result volume that the schema 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?

Two sentences, no filler, with the result set and ordering front-loaded before the usage hint. Nothing is redundant or buried.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety. The definition is adequate for a two-parameter read tool, though it omits any mention of workspace scoping behavior that a caller in a multi-workspace connection would benefit from.

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

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

Schema description coverage is 100%, so the baseline is 3; the description contributes no additional meaning about limit or workspaceId beyond what the schema already states, including the unusual 'no more than five are ever found' cap.

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 specific resource (published articles) and the exact signal (falling search clicks) plus an ordering ('worst first'), which is more than the title alone conveys. It is distinguishable from ranking/performance siblings by the 'decaying' framing, but it never names those siblings to draw the line 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?

'Use this to decide what to refresh before writing anything new' gives a decision context, but offers no explicit when-not-to-use guidance and never names an alternative such as readPerformance or readRankings for healthy-traffic lookups.

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, closed-world behavior, so the safety profile is covered. The description adds real context beyond that: the 30-day measurement window, the exact metrics returned, and the precondition that the workspace must have subscribed contacts. It doesn't discuss auth or rate limits, but those are not central for a read tool.

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

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

Two tight sentences with zero filler: the first front-loads what the tool returns, the second front-loads the when-to-use directive and the scope restriction. Nothing is repeated from the schema or annotations.

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 needn't be described, and the description covers scope (30-day window), contents (metrics), usage timing, and the workspace eligibility constraint. Nothing an agent needs in order to call it correctly is missing.

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

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

There is a single parameter (workspaceId) and schema description coverage is 100%, so the schema already explains what it is and when to omit it. The description adds no parameter-level guidance, which is acceptable at this coverage level but not above baseline.

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 ('Sending health over the last 30 days') and enumerates exactly what is measured: sent volume, bounce, complaint and unsubscribe rates, review/pause rates, and hold-back reasons. This is clearly distinguishable from siblings like readPerformance, readSiteHealth, or readScorecard.

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 directs when to call it ('Check this BEFORE proposing any send') and explains the consequence of skipping it, plus the correct alternative action when a bounce problem exists ('fix deliverability rather than to mail more'). It also states the eligibility condition: only for a workspace with subscribed email contacts.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the returned content is the entire document rather than an excerpt, but says nothing about size limits, truncation of very large documents, or what happens when the key does not resolve — real behavioral questions for a read tool.

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

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

Two sentences, zero filler, with the core action and the usage condition front-loaded and the key-provenance detail trailing. Nothing repeats the title or the annotations.

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, and the annotations carry the safety profile. The description covers purpose, selection condition, and key origin; only the failure mode for an invalid key is left unstated, a minor gap for a two-parameter 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 coverage is 100%, so the baseline is 3, but the description adds genuine provenance for the required 'key' parameter — that it originates from searchDocuments or listDocuments — which the schema does not state. It says nothing extra about workspaceId, though the schema field already explains its omission behavior.

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 ('Read') plus resource ('a full document from the knowledge base') with the addressing mechanism ('by its storage key') stated up front. It also implicitly distinguishes itself from the list/search siblings by emphasizing 'full document' rather than a snippet or result row.

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 trigger condition ('when a search result is not enough') and names where the key must come from ('searchDocuments or listDocuments'), which routes the agent away from guessing keys. It stops short of an explicit when-not-to-use statement or a note about bulk reading multiple documents.

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, and the description goes beyond them by disclosing the built-in-flow fallback (`builtIn`) when a flow has no emails, the 30-day window on metrics, and the fact that draftFlow overwrites a flow — a strong implicit warning to read first. It omits any statement about result size, ordering of the flows list, or limits.

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

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

The content is dense and every sentence carries information — the flow contents, the fallback rule, the read-before-write rule, the audience precondition. The opening sentence is a long run-on list, and the important audience gate is placed last rather than front-loaded, which slightly weakens 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?

An output schema exists, so return values need not be re-explained, and the description still covers the meaningful surprises (fallback flow, metric window, precondition). What is missing is minor: whether all flows are returned or paginated, and any ordering or size expectations.

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

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

With a single optional parameter at 100% schema description coverage, the schema already explains that workspaceId accepts an id or slug and may be omitted for single-workspace connections. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

The description names the resource (every automated email flow) and enumerates exactly what is returned: on/off state, store dependency, ordered emails with wait times and personalization, plus 30-day send/open/click metrics. The `draftFlow` reference makes the boundary between reading and rewriting a flow explicit, so an agent can separate this from siblings 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?

It gives an explicit sequencing rule ('Read it before draftFlow rewrites a flow') and a hard precondition ('Only for a workspace with subscribed email contacts'), which functions as a when-not condition. It does not address the other adjacent mutators (enableFlow, updateFlowStep), so the alternative routing is only partial.

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, closed-world safety, so the description's job is to add context beyond that – and it does, disclosing provenance (items handed over by the GEO agent when the brand is absent from a topic) and that each idea carries justifying evidence. It says nothing about volume, staleness, or what happens when the queue is empty, but the output schema covers the 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?

The resource definition and provenance are front-loaded in one efficient sentence, with the reading-order advice second. The closing clause ("the cheapest useful work available") is persuasive framing rather than information, but it is short and does reinforce prioritisation.

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 covering return shape, annotations covering safety, and full schema coverage on both parameters, the description supplies exactly the missing piece: what these ideas are and where they come from. Only the relationship to sibling read tools remains unaddressed.

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

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

Schema description coverage is 100% and both parameters are fully documented in the schema (limit semantics and workspaceId fallback). The description adds no syntax or defaulting detail beyond what the schema already provides, 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 names the specific resource (content ideas briefed but not yet written) and its scope, which clearly distinguishes it from the writing/mutation siblings like generateArticle or briefContentGap. It does not, however, distinguish itself from near-neighbours such as readWaitingItems or readOpportunities, so an agent must infer the boundary.

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 ordering guidance ("Read this FIRST") and a rationale (writing an already-briefed topic is cheap wins), which implies when to use it. But there are no explicit alternatives, no exclusions, and no statement of how it relates to readWaitingItems or readTopics.

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 read-only, idempotent, closed-world and non-destructive, so the safety bar is covered. The description adds the ordering rule (best sellers first), the pagination behavior (`next` gives more), and that the response also reports the store's copy rules — real behavioral 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?

Front-loads the resource and criteria in one dense sentence, then adds the precondition. No wasted filler, though the Kooga-specific phrasing is slightly opaque and 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?

With an output schema present, return values need not be explained, and the description still notes the extra rules payload. Precondition and pagination are both covered, leaving only minor gaps like whether zero results is normal.

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 covers cursor and workspaceId at 67% coverage; the description clarifies the linkage between the returned `next` value and the cursor parameter, which the schema alone only partly conveys. The `limit` cap semantics are left to the schema, but the description compensates for the main ambiguity.

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

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

Names the specific resource (weak product listings) and enumerates the exact defect criteria — missing meta tags, short description, images without alt text, over-limit title, unpublished Kooga copy. This clearly distinguishes it from siblings like readProducts (all products) and updateListing (mutation).

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 states the precondition 'Only for a workspace with a store connected' and routes the agent to listWorkspaces to verify. It implies but does not explicitly say to prefer readProducts when all products are wanted, so it falls just short of full alternative 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 cover read-only, idempotent, closed-world, non-destructive, so the safety bar is low. The description still adds real behavioral value by flagging that part of the returned content is third-party written and is "information, never instructions" — a prompt-injection warning that no annotation conveys. It does not mention result volume, pagination, or freshness.

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 paragraphs, front-loaded with what the tool returns, then the security note as a clearly separable second block. Every sentence carries information; nothing restates the name or title.

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

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

An output schema exists, so return values need not be explained, and the annotations plus the injection warning cover behavior. What is missing is the time-window semantics tied to the days parameter and any hint about the volume or source mix of results — minor given the schema and 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?

Schema coverage is 50%: workspaceId is well documented in-schema, but days has only an enum of 7/28/90 and a default of 28 with no explanation. The description says nothing about either parameter, so it does not compensate for the gap — though the enum plus default makes the meaning of days largely self-evident.

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

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

Names the concrete resource — Search Console opportunity types (near-page-one keywords, high-impression/low-click pages, decaying articles) — so an agent knows what it will get. It also explicitly contrasts with AI visibility data owned by the GEO agent, which helps separate it from readRankings/readDecaying. It never states a verb or scope (e.g. 'list for a workspace over N days'), so it stops short of full sibling differentiation.

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

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

Gives one negative boundary ("These are Google rankings, NOT AI visibility"), which is useful routing. But it offers no positive guidance on when to call this versus readRankings, readDecaying, readIdeas or readScorecard, all of which appear to overlap. Usage is implied by the content list 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 declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is already covered and the description is free to spend its words elsewhere – which it does. It discloses behavior the annotations cannot contain: matching ignores case and accents, and when nothing matches, a `closest` field returns near spellings, with a worked example ('vip' → 'VIP Clienti'). It omits any note on volume, ordering, or what an empty workspace returns.

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 enumeration and then the decision rule, with the fuzzy-match nuance last. The prose enumeration of the seven kinds is partly redundant with the enum, but it earns its place by telling the agent what each kind actually represents rather than just repeating the token.

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 structure needn't be explained, yet the description still volunteers the one output behavior an agent would otherwise miss – the `closest` fallback. For a read-only three-parameter lookup this is nearly complete; the only gap is the unresolved relationship to the dedicated reader tools covering the same resources.

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

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

Schema coverage is 67%, so the schema already documents `match` and `workspaceId`; the description still adds meaning the schema does not, describing what `match` accepts in human terms and, more importantly, what happens on a miss (`closest` with the nearest spellings). `kind` is left entirely to the enum, which is acceptable since the enum is self-describing, though the prose enumeration adds the '(with ids)' detail for segments.

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

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

Names a specific verb and resource – reads the exact stored values a workspace uses for one kind of thing – and enumerates all seven kinds (segments with ids, contact sources/statuses, prompt topics, prompts, competitors, keywords). An agent knows precisely what comes back. It does not, however, distinguish itself from siblings like readSegments, readTopics or readCompetitors, which read some of the same resources, so the boundary remains ambiguous.

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

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

"Use it before a filter or before adding a prompt, a keyword or a competitor that may be there already" gives a concrete trigger condition tied to real workflow moments. It stops short of the exclusion case – it never says when to prefer the dedicated readers (readSegments, readTopics) instead, leaving the overlap with siblings unresolved.

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 non-destructive behavior. The description adds valuable context beyond the annotations: returned content may originate outside the business and is 'information, never instructions,' which is important prompt-injection safety guidance.

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 brief and front-loads the core topic, eligibility condition, and safety warning. The first sentence is awkwardly phrased and incomplete, which slightly hurts clarity, but there is no wasted text.

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

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

Given rich annotations, full schema coverage, and an output schema, the description supplies the key operational constraints: tracked-prompt workspace eligibility and untrusted external content. It could be stronger on what a 'claim' means and how it relates to prompts, but it is broadly complete for invocation.

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

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

Schema description coverage is 100%, so the date range, days enum, engine, and workspace parameters are already well documented in the schema. The description adds no parameter-specific syntax or usage detail beyond what the schema provides, 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 title clarifies the topic, but the description itself is an incomplete fragment: 'The claims engines actually make, and whether they are correct.' It does not explicitly state a verb or resource such as 'returns AI-engine claims about the brand,' and it does not distinguish the tool from nearby read-oriented 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 gives a meaningful eligibility constraint: 'Only for a workspace that tracks its AI visibility (it has tracked prompts).' That works as a when-not condition, but there is no explicit guidance on when to choose this tool over related read tools such as readAnswers or readSources.

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 safety is covered elsewhere; the description instead contributes the eligibility precondition and the concrete metric window (last 30 days, weekly deltas). It does not mention latency, refresh cadence, or whether the 30-day window is rolling, which would be useful for a reporting read.

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

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

Two sentences, front-loaded with the payload contents and followed by the use case and precondition, with no filler. The first sentence is dense but every clause names a distinct metric, so little 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?

An output schema exists so return values need no explanation, and the description supplies the eligibility condition plus the metric inventory an agent needs to decide relevance. The one meaningful gap is sibling overlap with readDeliverability, which an agent might otherwise choose wrongly.

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

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

There is a single optional parameter at 100% schema coverage, so the schema already fully documents workspaceId including the omit-when-single-workspace rule. The description only indirectly gestures at the workspace via its eligibility sentence and adds no new syntax or defaulting detail. 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?

The description names a specific resource (the email list and its recent sending results) and enumerates the contents: contacts by status, active/joined/lost counts, 30-day bounce/complaint/unsubscribe rates, reputation score, and mailbox providers. That is far more specific than a restated title. It stops short of 5 because it never distinguishes itself from the sibling readDeliverability, which plausibly covers overlapping sending-health data.

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

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

"Use it to judge whether another send is welcome" gives a clear decision context, and "Only for a workspace with subscribed email contacts" states a precondition that should block a call. It does not, however, point to an alternative for workspaces without subscribed contacts or explain how it relates to readDeliverability/readCampaigns.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that: results reflect Kooga's last sync, `next` enables pagination, and `id` versus `storeId` have distinct downstream uses.

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

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

The description is front-loaded with the core resource and search behavior, then gives ID usage and usage constraints. It is dense but every clause provides operational value, and 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 present, the description need not explain return shape. It covers the workspace prerequisite, sync freshness, pagination, ID meanings, and the relevant sibling alternative, which is sufficient for an 8-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 88%, so most parameter meaning is already structured. The description still adds useful cross-tool semantics for `id`, `storeId`, `discountPct`, and `next`, though it does not add much to the already-described sort/filter parameters.

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 (products in the store), the core operation (search/filter/sort), and explicitly distinguishes it from readTopProducts for best sellers. It also ties product IDs to updateListing, draftCampaign, and readTopProducts, so an agent can route correctly among 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 gives an explicit prerequisite: only for a workspace with a store connected, with listWorkspaces as the way to check. It also names the alternative readTopProducts for best-seller data, leaving little ambiguity about when to use this tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds real interpretation context the annotations cannot: null means outside the top 20, null pieceId means the ranking page isn't a Kooga article, and a one-or-two place move is noise rather than signal.

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 the resource stated first and the field glossary after; the closing caution about noise earns its place. It is dense but every clause carries information, not 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 return values needn't be spelled out, yet the description goes further and pre-decodes the non-obvious field names (`pieceId`, `odds`, `previous`) and their null semantics. For a two-parameter read tool this is close to complete, with only the missing sibling routing keeping it from the top.

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 two parameters are fully documented in structured form and this is the baseline case. The description adds nothing parameter-specific — no explanation of what limit ordering means in practice or when workspaceId is required beyond what the schema already says.

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 ('Google positions for the keywords the merchant tracks') and enumerates what each returned field means. It implicitly separates itself from AI-visibility tooling, but never names a sibling such as readCompetitors or readOpportunities, so the 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 rather than stated — the agent can infer 'call this to see where tracked keywords rank'. The one genuine routing cue is the negative one ('These are Google rankings, NOT AI visibility'), which helps exclude a misread but gives no when-to-use/when-not conditions or named alternatives.

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 behavior. The description adds useful context about what a run contains and that `next` provides older runs, though it does not mention rate limits or auth constraints.

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 with no waste, front-loading what the tool returns and following with usage guidance and pagination. Every sentence contributes.

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 tool with optional parameters and an existing output schema, the description supplies the essential purpose, usage cue, and pagination behavior. Missing parameter details are adequately covered by the schema.

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

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

Schema coverage is 67%, with cursor and workspaceId documented but limit undocumented. The description mentions pagination via `next` but does not explain the `cursor`, `limit`, or `workspaceId` parameters directly, so it adds only marginal parameter meaning beyond the schema.

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

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

States a specific read operation over a specific resource (recent runs of every agent) and enumerates the returned content: last-worked time, merchant note, and proposed/done counts. This clearly distinguishes it from siblings like readStatus or readWaitingItems.

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 says to read it before saying what happened or what an agent decided, giving clear usage context. It does not name when not to use it or point to an alternative sibling, 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, so the safe-read profile is covered. The description still adds real behavioral context the annotations cannot: the tool fails or is irrelevant unless a store is connected, and listWorkspaces tells you which workspaces qualify.

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 sentences, front-loaded with what it returns and then the access constraint. Every clause carries information an agent needs; nothing is 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?

Output schema exists, so return-shape explanation is unnecessary, and the description covers purpose and the key gating condition. What remains thin is the relationship to adjacent sales tools (trend, top products, store overview), which an agent must infer from names.

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 four parameters (days, from/to, workspaceId) are already fully documented including enum values and date-range constraints. The description adds only the implication that results are grouped by channel, not any parameter-level guidance beyond the schema. 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 the concrete metrics returned (orders, revenue, units) and the grouping dimension (per connected channel), which is more specific than the tool name alone. It does not explicitly distinguish itself from close siblings like readSalesTrend or readStoreOverview, so the boundary is inferred 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?

Gives concrete user-intent examples ('which channel sells more', 'Shopify vs WooCommerce') that map directly to when to call it, plus an explicit precondition and exclusion: only for workspaces with a store connected. It stops short of naming a sibling as the alternative for non-store workspaces or for trend-over-time questions.

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 that this is a safe, read-only, idempotent operation. The description adds useful behavioral context beyond the annotations: results are zero-filled, aggregates only, and require a store-connected workspace.

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 core purpose front-loaded and the prerequisite placed second. There is no redundant or wasted wording.

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

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

The description covers the key domain constraints for calling the tool, especially the store-connected prerequisite and aggregate/zero-filled behavior. With a full input schema and an output schema present, no further explanation of return values is needed.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including enums and date constraints. The description reinforces the revenue/orders choice and the period concept but does not add meaningful parameter syntax 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 states a specific resource and measure: daily revenue or order count over a period, with example user intents. It is clearly distinct from most sibling tools, but it does not explicitly contrast itself with nearby analytics tools such as readPerformance or readCustomerStats.

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 concrete use cases ('revenue trend', 'are sales going up', 'orders per day') and a clear prerequisite: only for workspaces with a connected store, checked via listWorkspaces. It lacks explicit when-not-to-use guidance or named alternatives for adjacent analytics questions.

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/closed-world, so the safety profile is covered. The description adds real context beyond them: the tracked-prompts precondition, the note that unbranded prompts are the 'honest measure', and the default bucketing behavior implied by `interval`.

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 tightly packed paragraphs — metric description first, alternative and precondition last. No filler, though the sentence about `byCountry`/`country` is dense enough to require a second read.

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 needn't be explained, and the description still sketches the result shape. With 7 optional params, all schema-documented, plus a stated precondition, an agent has what it needs to call 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 every parameter is already documented with patterns, enums and defaults. The description largely restates that (`interval`, `country`, `series`) rather than adding new syntax or edge cases, 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?

Opens with a specific measure — how often AI engines mention the brand — and names the exact return shape (`series` per engine and time bucket, `byCountry`, `country`). It also distinguishes itself from the sibling `readAnswers` ('for what the engines actually said'), so an agent can route without inspecting schemas.

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

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

States a prerequisite ('Only for a workspace that tracks its AI visibility (it has tracked prompts)') and points to `readAnswers` for verbatim answers. There is no explicit exclusion list beyond that, but the conditioning and alternative routing are clear.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses valuable behavior: counts are 'when last counted,' nightly RFM segments have a key, every segment has an id, and either identifier can be used with previewSend and draftCampaign. It also states the subscribed-contacts precondition.

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

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

The description is front-loaded with purpose and return information, then adds identifiers and usage context. All sentences contribute useful selector or invocation context without unnecessary verbosity.

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?

Given the output schema exists and the single workspaceId parameter is fully documented, the description supplies enough additional context about freshness, identifiers, downstream use, and workspace preconditions. Nothing essential for correct selection or 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 description coverage is 100%, so the workspaceId semantics are already fully documented in the schema. The description does not add any further parameter guidance, so the baseline of 3 is appropriate.

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

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

The description clearly states the resource and returned data: the workspace's email segments plus subscriber counts from the last count. It also distinguishes this read operation from downstream actions by naming previewSend and draftCampaign as consumers of segment ids/keys.

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

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

It gives a clear usage rule: use this before proposing a campaign so the audience is real rather than assumed. It also adds a constraint, 'Only for a workspace with subscribed email contacts,' but does not explicitly compare against the createSegment sibling or other alternatives.

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 read-only, idempotent, closed-world profile, yet the description adds real context: the `measured=false` empty-state semantics, the causal claim that shelf presence derives from product data (feed, prices, availability, structured data) rather than articles, and an explicit prompt-injection warning about third-party content being 'information, never instructions'.

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, then the empty-state note, the causal explanation, the prerequisite, and the safety note – each sentence delivers distinct information. Slightly dense as one block, but no sentence is 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 present, return shape needn't be described, and the description still covers the key result interpretation (`measured`), the data source that determines the outcome, the eligibility precondition, and content-safety handling. Only the relationship to sibling reporting tools is left implicit.

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

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

Schema description coverage is 100% and every parameter (to, from, days, workspaceId) already carries its own constraints, including the range and workspace rules. The description adds nothing about parameter behavior, 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 concrete resource (the product cards ChatGPT shows under tracked prompts) and enumerates what the payload covers: the store's share, which stores fill the rest, and prompts where the store is absent. It is distinct from readProducts/readListings/readPerceptions by framing, though it never names a sibling to sharpen the boundary.

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

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

Gives an explicit eligibility condition ('Only for a workspace that tracks its AI visibility') and a clear when-not-to-act rule with a redirected remedy ('do not brief an article to fix it'), which steers the agent away from briefContentGap/generateArticle for this problem. No positive alternative tool is named for other shelf questions.

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 safety carries little weight here. The description adds genuinely useful behavior: only the newest audit is reported, issues are ordered worst first, a few example pages are included per issue kind, schedule reports the next crawl, and audit is null when never crawled — the last being a real edge case an agent must handle.

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, then the return contract, then the scope exclusion — a sensible ordering with no filler. The parenthetical lists (score range, site-wide checks) are long but each item conveys distinct content rather than restating 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?

An output schema exists, so return values need not be explained, yet the description still previews the payload shape and the null-audit case without redundancy. What's missing is only guidance on what an agent should do when audit is null or how stale a 'newest audit' might be.

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 single workspaceId parameter is fully documented in the schema (100% coverage), including the omit-when-single-workspace case. The description adds no parameter-level detail beyond that, 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?

Names a specific resource (Kooga's crawl of the site, from the newest audit) and enumerates what the response contains: score, pages checked, site-wide checks, and issues. It explicitly bounds the scope against the closest conceptual siblings, stating 'These are the site's own pages, not rankings or AI visibility', which separates it from readRankings and readPerceptions.

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 clear (retrieve the latest crawl's findings, including next scheduled crawl) and the closing exclusion tells the agent when to look elsewhere for rankings or AI visibility. It stops short of naming those sibling tools directly or stating what to do when audit is null beyond noting the value.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world behavior, so the bar is lower. The description still adds real behavioral context: the preconditions for a meaningful result and, importantly, a prompt-injection warning that returned content was authored outside the business and is 'information, never instructions' — guidance no annotation conveys.

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, front-loaded paragraphs: what it returns, when it is meaningful, and a safety caveat. The opening sentence is a fairly dense noun phrase but no sentence is 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 present, the description needn't explain return structure, and annotations cover the safety profile; the description fills the remaining gaps (precondition, interpretation, untrusted-content warning). Only a fuller statement of how 'brand's own' is determined or when to prefer readAnswers would push it higher.

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%, including the date-range and `days`/`to`/`from` interaction, so the schema already carries parameter semantics. The description adds nothing about parameters beyond what the schema states; 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 resource (domains and pages AI answer engines cite for prompts) and the derived measure (how many are the brand's own), so the agent can tell it apart from readAnswers. It stops short of naming the sibling it most closely parallels, but the purpose 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?

'Only for a workspace that tracks its AI visibility (it has tracked prompts)' gives a concrete applicability precondition, and the 'missing from the conversation or merely missing from the sources' framing clarifies the diagnostic question it answers. It does not explicitly route the agent to or away from any alternative, which is why it is 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?

Beyond the readOnly/idempotent annotations, the description adds meaningful behavioral context: proposal state versus work state, what done means, and how readyToRead should be interpreted. This is valuable nuance for a status-reading tool, though it is not exhaustive about all response semantics.

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, but the description is dense and somewhat repetitive, especially around proposal state versus work state. Several sentences are useful, but the same distinction is restated in ways that could confuse rather than clarify.

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