Replo

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

Adds substantial context beyond annotations: cancellation interrupts unfinished work, may leave partial changes, completed changes are not rolled back, and the session is retained. These are exactly the behavioral traits an agent needs before invoking a destructive operation.

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

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

Three short sentences, front-loaded with the primary action and followed by the most important side effects. Every sentence earns its place.

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

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

For a destructive mutation with no output schema, the description covers the key effects and retention behavior well. The main gap is that the single required parameter, sessionId, remains completely undocumented in both schema and description.

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

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

Schema coverage is 0%, so the description must compensate, but it never mentions sessionId, its format (UUID), or where to obtain it. The only hint is 'of a Replo session,' which is insufficient for the sole required parameter.

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: cancel the in-progress turn of a Replo session. The scope ('in-progress turn') clearly separates it from related tools like get_agent_session, 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?

Usage is implied by the phrase 'Cancel the in-progress turn,' but there is no explicit guidance on when to choose this over get_agent_session or resolve_agent_interaction. No exclusions or alternatives are given.

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

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

Annotations already flag destructiveHint, openWorldHint, and non-idempotent, but the description adds beyond them: the operation is asynchronous and must be polled with get_agent_session, edits may execute in the site's preview, and corrections reuse the same sessionId with an unchanged target. That is exactly the operational context the hints 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?

Purpose, side-effect scope, prerequisite, and alternatives are front-loaded in the first few sentences. A couple of sentences (the Replo agent description, the publish_site reminder) are supportive rather than essential, keeping it just under maximum density.

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

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

Without an output schema, the description still tells the agent what to expect (an internal-agent session to poll via get_agent_session) and how to continue or correct a run. For a destructive, async, three-parameter tool this covers everything needed 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, and the description earns a bump by framing sessionId in the real correction workflow ('call this same tool with its sessionId and unchanged target'), reinforcing the mismatch-rejection behavior. It adds little about 'instructions' beyond the schema, so it stays short of 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?

States a specific verb and resource with concrete scope: it copies the saved brand onto the selected site's shared style tokens, fonts, layout, and shared components. It explicitly clarifies it 'Affects that site's drafts, not the saved brand kit', which separates it from update_brand and publish_site without the agent opening either schema.

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

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

Gives explicit prerequisites ('Use update_brand first if there is no saved brand', 'Requires a provisioned site'), names the follow-up tool (publish_site) with a when-to-use condition, and describes the correction path via sessionId. Little is left to inference.

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

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

The annotations already establish that this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds useful behavioral context: it creates a pending domain and returns DNS records, and it warns against a dangerous misconfiguration involving Shopify checkout. It does not mention auth requirements or duplicate-call behavior beyond the idempotency annotation.

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

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

The description is three tight sentences, front-loaded with the action and immediate result. The warning is placed after the core behavior and every sentence contributes useful information.

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

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

For a two-parameter mutation with no output schema, the description is nearly complete: it explains the side effect, the returned DNS records, and a critical exclusion. The only minor gap is that it does not explicitly route the agent to the verification or status sibling tools.

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

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

Schema description coverage is 0%, but the schema itself provides formats and a domain pattern. The description adds only high-level meaning by mapping the domain to a Replo site, without explaining siteId or domain constraints beyond that. This is minimally adequate but does not fully compensate for the missing parameter descriptions.

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

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

The description states a specific verb and resource: beginning connection of a custom domain to a Replo site. It also clarifies the immediate effect by saying it creates a pending domain and returns the DNS records needed before verification. This is enough to distinguish it from status-checking and verification 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 clearly indicates this is the starting step for custom-domain setup, with verification only possible afterward. It also gives a strong exclusion: never connect a Shopify store's primary domain. It does not explicitly name verify_custom_domain as the next tool, so it stops 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 only declare readOnlyHint/idempotent/no-destroy, so the description must supply the actual behavior — and it does: the call surfaces a user-facing sign-in/Allow prompt, returns the user's identity, and is idempotent in the sense that re-calling re-raises the same prompt. What's missing is failure behavior (user declines, account creation fails, what the tool returns in those cases).

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

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

Dense but front-loaded with the core action and the primary exclusion. There is mild redundancy: the 'call the tool that returned it again' advice in sentence three is restated in the closing sentence, which repeats the same condition in different words without adding information.

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

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

With zero parameters, no output schema, and annotations covering the safety profile, the description does nearly all that is required: it explains the prompt flow, the follow-up chain to list_workspaces, and the re-invocation rule. It stops short of describing what happens on user refusal or a failed sign-in, which an agent handling that branch would want.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description does not need to explain inputs at all.

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 ('Connects a chat that isn't connected to Replo yet') and immediately explains the mechanism: the chat app prompts the user to sign in or create an account and click Allow. This clearly separates it from the other connect-style sibling (connect_custom_domain) and from the rest of the Replo tool set.

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

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

Explicit when-not-to-call ('Don't call it when Replo tools already work'), explicit when-to-call conditions ('only when the user asks to connect this chat, or when that call returned another sign-in link'), and an explicit alternative action (re-call the tool that returned the sign-in link to re-trigger the same prompt). All three dimensions of routing guidance are present.

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

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

Goes well beyond the annotations (destructiveHint=true, readOnlyHint=false): it discloses that the secret is returned exactly once, that creating a user key beyond ten live keys revokes the least-recently-used key (unused first), and that the secret must be handled via stdin and never printed or committed. These are non-obvious side effects and handling requirements an agent could not infer.

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

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

Front-loaded with the core action and the type distinction, then layers side effects and secret-handling rules. Dense but each sentence carries distinct information, though the skill-pointer and list_sites/clone_url remark sit slightly apart from the main flow.

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 supplies the return shape (secret once plus structured Git host/username) and the destructive side effect of key revocation. Combined with the per-type constraints, an agent has everything needed to call this 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 67% and the description largely restates what the schema already says about type, projectIds, and expiresInDays. It adds the useful cross-field rule (user keys must expire, project keys may never expire) but leaves name and workspaceId unaddressed, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Create a Git API key') and immediately distinguishes the two modes (user vs project) that define the tool's behavior. Nothing in the sibling list does anything similar, so an agent can identify it without ambiguity.

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 guidance: user type for a coding agent acting on your behalf (Codex/Claude Code), project type for CI or automation touching named projects only. It also names the constraint that projectIds must be projects you can manage and that user keys must expire, so the selection criteria are fully spelled out.

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-readonly, non-destructive, non-idempotent, closed-world write, so the bar is lower; the description still adds real context — creation is private by default, defaults to My Files, runs in about a second, and returns a folder ID plus viewer link that must be fed to show_artifact. It does not say what happens on repeat calls with the same title, which matters given idempotentHint=false.

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?

Long but dense and front-loaded: the save action and file-keying model come first, follow-up calls next, the alternative sibling last. A few clauses (report.insights.json rendering, Insights report semantics) duplicate the schema's files description and could be trimmed without loss.

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 covers what matters: the artifact folder ID and viewer link are named, and the agent is told the exact next call. Combined with a nested files object and 80% schema coverage, nothing an agent needs to invoke 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 80%, so the schema already carries the parameter burden, and the description largely restates it: files keyed by path, index.html as the page, *.insights.json as reports, and parentId defaulting to My Files are all documented in the schema text. It adds little syntax or format detail beyond that 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?

"Save a new HTML artifact in Files from files you wrote" gives a specific verb, resource, and source, and the closing sentence distinguishes it from generate_artifact (research-and-write) and implies update_artifact handles changes. An agent can select it against its siblings 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?

Explicit routing is provided in both directions: use generate_artifact when the request is in words, call show_artifact after creation so the user sees it, and call set_file_sharing only when the user asks to share. Prerequisites and follow-up sequencing are spelled out rather than inferred.

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

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

Goes beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing attribution semantics ('attributed to the signed-in user') and a content trust boundary — comment bodies are third-party data, not instructions. It does not explain return behavior or retry positioning beyond what the schema already states for id/commentId.

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

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

Three sentences, front-loaded with the action and targets before the usage constraint and the safety note. Nothing is redundant, though the last sentence is dense and could be split for scanability.

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

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

For a mutation tool with five parameters, annotations present, and no output schema, the description covers action, target scope, attribution, the user-consent gate, and prompt-injection handling — the residual gaps (return value shape, anchor param) are already 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 60%, so the schema already documents body, anchor, id, commentId, and the target union in detail. The description adds only the target enumeration and the author-attribution fact, neither of which clarifies the undocumented remainder; it does not mention anchor, idempotent retry via id/commentId, or the anchor restrictions on site page/order targets.

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 ('Start') plus resource ('a comment thread') and enumerates the four valid target kinds (file, site page, order, asset). The verb 'start' implicitly distinguishes it from sibling reply_to_comment_thread, and the target enumeration tells an agent exactly which entities can be commented on.

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 comment when the user asks' is an explicit when-to-use guardrail that rules out proactive commenting. It stops short of naming sibling alternatives (reply_to_comment_thread, resolve_comment_thread, list_comment_threads) as the follow-up path for existing threads, so routing to siblings is left to inference.

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

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

Annotations declare the mutation safety profile (non-destructive, non-idempotent), and the description adds genuinely new behavioral facts: asset sources are copied without deleting the original, and name conflicts never overwrite. These are exactly the kind of side-effect disclosures an agent needs 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?

Four compact sentences, front-loaded with the core action, each adding a distinct behavioral fact. No filler, though the source-requirement sentence is somewhat dense.

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

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

For a mutation tool with no output schema and low schema coverage, the description covers the trickiest parameter (source) and key side effects, but omits where the file is placed (parentId/projectId) and what is returned. Adequate but with clear gaps.

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

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

Schema coverage is only 20%, so the description carries real weight. It correctly explains the source requirement logic (text/base64/asset for files, omitted for folders), but leaves projectId, parentId, and name constraints undocumented in both schema and description.

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 ('Create a private document or folder in Files') and clarifies the file-vs-folder distinction. It is clearly separable from siblings like get_file or upload_asset, though it doesn't explicitly contrast itself with those.

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 file/folder distinction implies when to use which kind, but there is no explicit guidance on when to choose this over upload_asset or create_artifact, nor any stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a useful behavioral detail: "New products are active immediately." However, it does not explain permissions, side effects, uniqueness behavior, or what happens to related inventory.

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 two sentences, front-loads the action, and contains no filler. Both sentences convey relevant information without repetition.

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

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

For a create tool with five undocumented parameters and no output schema, the description is too sparse. It covers purpose and immediate activation but omits parameter semantics, required project association, slug behavior, and any indication of what is returned.

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

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

Schema description coverage is 0% for five parameters, and the description does not explain any parameter names or meanings. It does not clarify required fields like title and projectId, nor optional fields like slug, description, or externalCheckoutUrl.

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 uses a specific verb and resource: "Create a Replo-managed product," and adds scope with "for native product pages or checkout flows." It is clear what the tool does, though it does not explicitly differentiate itself from sibling tools like update_product, get_product, or find_products.

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

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

The phrase "for native product pages or checkout flows" implies when this tool is appropriate, but there are no explicit when-not conditions, prerequisites, or named alternatives such as update_product. Usage guidance is therefore present but only implied.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent, closed-world write. The description adds real value on top: it states a validation constraint ("eligible workspaceId") and a concrete side effect ("this changes the workspace's project list"), plus what is returned. It stops short of describing failure modes or duplicate-name behavior.

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

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

Two sentences, zero waste, with the workspace/ID requirement front-loaded ahead of the return and side-effect note.

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 2-parameter create tool with no output schema, the description covers inputs, return, and the workspace-level consequence. Only the eligibility definition and error/duplicate behavior are missing, which are minor for this complexity.

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 0%, so the description must carry the parameter burden. It does name both parameters and adds the source of workspaceId (list_projects) plus the selection criterion, but leaves the name constraints (1-256 chars) and the actual meaning of "eligible" undefined.

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

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

Specific verb+resource ("Create a Replo project") with a stated scope ("in a workspace"). It does not explicitly contrast with update_project or get_project, so the sibling differentiation is only implied by the verb.

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

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

Gives a concrete prerequisite and even names the sibling that supplies it: "Requires an eligible workspaceId from list_projects." No when-not-to-use guidance or exclusions are stated, and "a workspace selected for the user's requested work" stays vague about what makes a workspace eligible.

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 real context beyond the annotations: the link is publicly viewable by anyone with the URL, it uses the account's existing preview workspace, availability is resolved lazily when the link opens, and no publishing/editing occurs. Gaps remain on what the call actually returns (the link? an existing link on 'recover'?) and whether access can be revoked later.

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

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

Four dense sentences, front-loaded with the core action and followed by ID sourcing, locale default, and safety guardrails. Every sentence carries usable information; only the 'page availability is checked when the link opens' sentence is slightly tangential to 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?

With no output schema, the description implies but never states what is returned (the preview URL or an existing one on 'recover'). Otherwise it covers prerequisites, public-visibility implications, idempotent recovery, and the no-publish guardrail well enough to call it correctly.

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

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

Schema coverage is 50% (route and locale documented; siteId and projectId undocumented). The description usefully compensates by naming list_projects and list_sites as the source of the two bare UUIDs, and reinforces the locale-omission default, but adds no format or constraint detail for those IDs.

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+scope: 'Create or recover a public live preview link to a site page without publishing.' The 'without publishing' clause cleanly separates it from publish_site and revoke_shared_preview in the sibling list.

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

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

Gives concrete routing guidance ('Use projectId from list_projects and siteId from list_sites') and a conditional trigger ('Share only when requested'). It also names a non-usage branch (missing preview workspace -> report, don't edit/publish), but never explicitly names publish_site as the alternative when actual publishing is wanted.

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 that this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds useful behavior: it creates a git repository, defaults the template to 'blank', returns clone_url, requires a repo key from create_api_key for cloning, and clarifies that creation does not publish.

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

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

The description is three dense sentences with no wasted wording. The core action and key caveat are front-loaded, and the follow-on Git cloning detail is placed after the primary behavior.

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 creation tool with annotations and no output schema, the description covers the essential context: what is created, where projectId comes from, the template default, what is returned, how to clone the repo, and the important non-publication limitation.

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

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

Schema coverage is 67%, and the description compensates for the undocumented projectId parameter by specifying that it comes from list_projects. It also reinforces the name purpose and template default beyond the schema descriptions.

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

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

The description gives a specific verb and resource: create a site, and expands it to include the git repository forked from a starter template. It distinguishes the operation from publishing by stating that creating a site does not publish it, so an agent can tell this apart from publish_site.

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

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

It states the prerequisite for projectId ('from list_projects') and gives a clear exclusion ('does not publish it'). It does not explicitly route between create_site and sibling creation tools such as create_project or create_site_page, but the operational 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 flag destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description adds real context beyond them: the operation is asynchronous, must be polled via get_agent_session, requires a provisioned site, and may execute source edits in a preview. The note that the Replo agent uses connected integrations and normal tools also warns of side effects. It doesn't explain what specifically makes it destructive, which keeps it below a 5.

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

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

The critical facts (create draft, preserve pages, async + poll) are front-loaded, and every sentence is functional. The sentence about the Replo agent using its normal tools and integrations is the most expendable, keeping it from a 5.

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 4-parameter asynchronous mutation with no output schema, the description covers the full agent loop: prerequisites, what to put in instructions, how to poll (get_agent_session), how to iterate on corrections, and how publishing is separated. An agent has everything needed to call it and handle the result 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 baseline is 3, but the description adds genuine semantics: instructions should carry copy, layout, product references and design requirements, and sessionId is the continuation handle for corrections with an unchanged target. That is more than the schema alone conveys, though it doesn't clarify the route pattern or the 7500-char limit.

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

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

The description opens with a precise verb+resource+scope: "Create a draft page at one route in an existing site," which immediately distinguishes it from edit_site_page and delete_site_page. "Preserve existing pages" further narrows the semantics, so an agent can tell it is additive rather than mutating existing routes.

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

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

It names an alternative for the follow-on step ("Use publish_site separately to make changes public") and states the correction path (re-call with the same sessionId and unchanged target), plus the prerequisite that a site must be provisioned. It stops short of explicitly contrasting with edit_site_page/delete_site_page, so it's clear context without full exclusion guidance.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds real context beyond them: the published copy survives, the call kicks off an asynchronous internal-agent operation requiring polling of get_agent_session, source edits may run in preview, and a provisioned site is required. It stops short of describing failure modes or what the session returns, which keeps it off a 5.

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

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

The key facts (what is removed, what survives, async + poll, correction path) are front-loaded and earn their place. The trailing sentence about the Replo agent's normal tools and integrations is generic boilerplate that dilutes an otherwise tight description.

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

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

For a destructive async tool with no output schema, the description covers the full lifecycle: precondition, effect, what is preserved, how to follow up (poll get_agent_session, publish_site), and how to correct. An agent has everything needed to call 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, but the description adds meaning the schema only partially conveys – notably that sessionId is used with an unchanged target for corrections and that mismatches are rejected. This slightly exceeds the schema-documented 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?

States a specific verb and resource ('Remove the selected route's draft page') and immediately delimits scope: published copy stays live, and the site and other routes are untouched. This distinguishes it cleanly from create_site_page, edit_site_page, and publish_site.

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

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

Gives explicit when/when-not: use to remove a draft, not to take a site down, and use publish_site separately to make changes public. It also specifies the correction path (reinvoke with the same sessionId and unchanged target) and the precondition (a provisioned site).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description nonetheless adds real information beyond them: deletion is permanent and it cancels all future scheduled runs, which clarifies the blast radius. It omits what happens if the taskId is invalid or whether confirmation is expected.

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, zero filler, and the irreversible nature is front-loaded in the leading adverb before the routing hint.

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 one-parameter destructive tool with rich annotations and no output schema, the definition covers purpose, effect, and when to use it. Minor gaps remain around failure behavior (task not found) and whether an explicit user confirmation is required before calling.

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

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

There is a single parameter with 100% schema description coverage ("ID of the scheduled task to delete"), so the schema fully documents it. The description adds nothing about the taskId itself (format, where to get it), which is the expected baseline 3 when the schema does the work.

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 ("Permanently delete a scheduled Replo task") plus the effect ("stop all future runs"), which makes it trivially distinguishable from read-side siblings like get_task and list_tasks as well as the other delete_* 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?

Gives an explicit when-to-use condition: "Use this when the user no longer wants a scheduled prompt to run." It does not name a when-not case (e.g., temporarily pausing vs. deleting) or mention checking the task first via get_task/list_tasks, so it stops short of a full routing statement.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds substantial context: shared component edits may leak to other pages, the call is asynchronous and must be polled, source edits may run in preview, and the backing agent uses connected integrations. It stops short of describing failure modes or how long the async operation typically takes.

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

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

Front-loaded with the core action and scope, followed by operational caveats in descending priority. It is somewhat dense at six sentences, and the sentence about the Replo agent's tools is the least essential, though it does frame the instructions parameter.

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

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

With no output schema, the description correctly explains the async contract and the polling path, plus the prerequisite and the publish boundary. An agent has everything needed to invoke it and handle the result without guessing.

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, and the description adds genuine meaning on top: sessionId is framed as a continue-versus-start switch tied to the same target, and instructions is characterized as a request handed to an internal agent (with a caution against secrets and conversation history).

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 (edit), resource (the selected site's draft page), and scope (one route, covering copy, sections, product display, forms, page-local components). It is clearly distinguishable from create_site_page, delete_site_page, update_site_navigation, and publish_site, the latter of which it explicitly routes away to.

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

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

Gives explicit when-to-use conditions: requires a provisioned site, omit sessionId to start, supply sessionId with unchanged target for corrections, and use publish_site separately to make changes public. It also names the follow-up tool (get_agent_session) for polling.

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

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

Annotations already carry the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context beyond that. It contributes the fact that retrieval can be semantic/ranked or metadata-filtered, which materially changes what comes back, but stops short of describing ranking, default ordering, or pagination behavior.

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

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

One front-loaded sentence with no filler and the resource named before the query modes. It is efficient, though the brevity contributes directly to the coverage gaps elsewhere rather than reflecting disciplined economy.

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

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

For an 8-parameter, no-output-schema read tool with low schema coverage, the description is too thin: an agent gets no guidance on pagination via cursor/limit, filter combination, or default result set. It is technically accurate but not sufficient to drive correct invocation on its own.

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

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

With only 38% schema description coverage across 8 parameters, the description needs to carry meaning for tags, label, limit, and searchTerm. It gestures at two parameter groups (search term vs metadata) but never maps them, and limit, label, and the tags array are entirely undiscussed in both places.

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 (find) and resource (media and files in a project's asset library) and names the two retrieval modes, semantic search and library metadata. It is clearly distinguishable from write-side siblings like upload_asset or update_file, but it does not distinguish itself from list_files, which is the closest read alternative.

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

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

"Using semantic search or library metadata" implies two usage paths but never says which conditions should push an agent to one or the other, and never names list_files or get_file as alternatives. The agent must infer from the schema that searchTerm triggers the semantic path and the other filters trigger the metadata path.

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, closed-world, so the bar is lower; the description still adds genuinely new behavioral context by disclosing that results are summaries only and exclude customer contact details and payment identifiers. The minor-units money convention is also behavioral information an agent would otherwise get wrong.

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, purpose first, then return-scope caveat, then the customerEmail routing hint, then the money-format note. Every sentence carries non-redundant information and none repeats 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?

With no output schema and five parameters at 20% description coverage, the description should carry more of the load. It covers the return shape and money encoding, but leaves pagination (limit/cursor) and the required projectId scope unexplained, which matters for correct 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 coverage is only 20%, and the enum's schema description is just 'OrderFinancialStatus', so the description has to compensate. It does explain customerEmail's practical use and implies financialStatus semantics via 'payment state', but says nothing about limit, cursor, or projectId, leaving pagination behavior undocumented.

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 ('Find storefront orders') and adds a concrete investigative purpose ('when investigating a payment state or fulfillment state'), which separates it from catalog-oriented siblings like find_products. It does not explicitly distinguish itself from get_order, which is the closest sibling, so it stops short of full 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 clear usage context (payment/fulfillment state investigations) and a concrete routing hint: use customerEmail to look up a known customer's orders. It never states when to prefer get_order over this tool, so the alternative-selection guidance is incomplete.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world, so the bar is lower. The description adds genuine beyond-schema context: the tool only returns Replo-managed products, and the recommended user-facing action when the result is empty.

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 filler, and the scope statement is front-loaded. Slightly redundant in restating 'products' twice, and it spends space on empty-state messaging while omitting pagination behavior.

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, four zero-documented parameters, and pagination available via cursor/limit, the description should at least indicate the shape of the result (a list of products with a next cursor). Instead it covers only the data domain and an empty-state hint, leaving the calling contract underspecified.

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

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

Schema description coverage is 0% across four parameters, and the description says nothing about projectId, query, limit, or cursor. An agent gets no hint that this is searchable or paginated (limit max 100, cursor-based), so the description fails to compensate for the undocumented 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 ('Find') and resource ('Replo-managed products'), plus the use cases (catalog, product-page, checkout work). It also distinguishes the product set from Shopify-managed products, though it doesn't explicitly contrast with the singular get_product sibling.

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

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

The description's exclusions are about data scope (not Shopify-managed products) rather than tool selection, so it doesn't say when to use this versus get_product, create_product, or update_product. The fallback instruction for empty results is helpful but is a post-call behavior, not a selection rule.

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

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

Beyond the annotations, the description discloses the asynchronous internal-agent workflow, the validation step, the polling behavior via get_agent_session, the final message contents, private-by-default creation, in-place revision preserving identity and sharing, and session continuation semantics. These are meaningful behavioral details not already captured by the annotations.

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

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

The description is longer but front-loaded and tightly structured; each sentence carries operational instructions for revision, asynchronous polling, session continuation, idempotency, sharing, and alternative tools. The length is justified by the multi-step asynchronous workflow being described.

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 complex asynchronous tool with no output schema, the description explains the full lifecycle: start the operation, poll get_agent_session, obtain the saved artifact folder ID and viewer link, call show_artifact, continue with sessionId, and handle sharing. No critical invocation or follow-up context 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 high at 83%, so the baseline is 3, but the description adds practical meaning for fileId (artifact folder ID, identity and sharing preservation), sessionId (follow-up only, mismatch rejection), operationId (fresh per new instruction, identical retry only), and sources (existing reports, analytics, or files). It does not fully describe the source filter/query schema, but that is appropriately left to the detailed 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 uses specific verbs (research, write, save) and identifies the resource (artifact), including Insights reports. It explicitly names create_artifact and update_artifact as alternatives when the files already exist, so an agent can distinguish this tool from sibling artifact 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?

It gives explicit when-to-use and when-not-to-use guidance: omit fileId for a new artifact, pass fileId to revise, use sessionId for follow-ups, reuse operationId only for identical retries, and use create_artifact/update_artifact when files already exist. It also describes the required polling step with get_agent_session, the follow-up show_artifact call, and the separate set_file_sharing call when sharing is requested.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine value by disclosing the return contents (no output schema exists) and the blocking interaction workflow, but it doesn't say whether responses are truncated, paginated, or how often to poll.

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 what is returned, followed by when to use it, then the conditional follow-up workflow. No filler and no repetition of the title 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?

With no output schema, the description carries responsibility for describing returns and does so field by field, plus it documents the multi-step interaction-resolution workflow. For a single-parameter read tool that is everything an agent needs to call it and act on the result.

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

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

There is a single required parameter, sessionId, and the schema supplies only its type and uuid format with 0% description coverage. The description never clarifies where sessionId comes from (presumably returned when starting a session), so it neither compensates for the coverage gap nor misleads; with one trivially obvious parameter this is adequate but not additive.

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 (retrieve) and resource (Replo session) and enumerates exactly what is returned: status, latest response, tool activity, errors, and pending interactions. This clearly separates it from siblings like abort_agent_session and resolve_agent_interaction, which mutate or resolve rather than fetch.

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 use case ("check progress after starting or continuing a session") and a concrete conditional branch: when pendingInteractions is non-empty, surface them to the user and then route to resolve_agent_interaction. It even specifies the argument shape for the follow-up call, so the agent knows both when to call this and what to do with the result.

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 the useful context that this backs a live UI card rather than a user-facing read, but says nothing about failure behavior when fileId or chartPath is invalid, or what the returned context looks like.

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, zero padding, with the purpose stated first and the usage restriction immediately after. 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 a two-parameter, fully documented, annotated read tool with no output schema, the description supplies the one thing the agent most needs: that it should not be called directly. Return-value detail is unnecessary here because the tool is explicitly not for agent consumption.

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 itself already warns that fileId is the .artifact folder ID and never an embedded report file ID. The description adds no parameter meaning beyond that, 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 identifies a specific function: supplying context so the artifact card can draw a live Insights report. It is clearly distinct from get_insights_report, though the verb 'get' plus 'context' is less concrete than a description of what data is actually returned.

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

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

It states explicitly that this is not for direct use and names the correct alternative (get_insights_report) for reading a report. An agent cannot mistake the routing, which is exactly the guidance needed for an internal-only 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context that this is a UI-driven loader, but says nothing about what is returned (access list? the artifact payload?) or why it is marked non-idempotent, which is the one annotation trait that would benefit from explanation. With annotations present, a 3 is appropriate.

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, zero filler, with the identity of the tool front-loaded and the routing instruction immediately after. Nothing could be removed 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?

For a single-parameter, read-only, internal tool with no output schema, the definition gives an agent everything needed to decide not to call it. The only missing piece is what the call actually returns or what happens if an agent calls it anyway, which is a minor gap given how strongly it is discouraged.

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 itself already warns that fileId must be the .artifact folder ID and never an embedded report file ID. The description adds no meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a concrete action ('load the artifact it shows') and names its caller context (the artifact card) plus the sibling to use instead (show_artifact). An agent can tell it apart from show_artifact without opening either schema. Minor gap: the name says 'view access' while the description says 'load the artifact', leaving a small ambiguity about what is actually fetched.

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 'Not for direct use' and names the alternative ('call show_artifact to show an artifact'), which is a full when-not plus routing instruction. This is exactly the kind of exclusion guidance that prevents misuse of an internally-scoped 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, but the description adds substantial behavioral context beyond them: empty-brand semantics, extraction polling protocol, the meaning of imported website status values, and the fact that this does not start an agent session.

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-loaded: it opens with what is read, then covers empty-state behavior, extraction polling, read-only status, file-access routing, and session scope. Each sentence contributes operational information rather than restating the name or 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?

With no output schema and a complex return shape, the description compensates by enumerating the returned sections and explaining empty-brand and extraction states. For a read-only single-parameter tool with rich annotations, nothing essential for correct invocation is missing.

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

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

There is one required parameter, projectId, and the schema description coverage is 100%, so the schema already fully documents it. The description does not add syntax or meaning beyond the schema for projectId; the baseline of 3 applies when the schema carries parameter documentation.

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 uses a specific verb-resource pair ('Read the live brand') and enumerates the exact contents returned: version, facts, overviews, colors, fonts, marks, personas, context files, imagery, and Figma designs. It clearly distinguishes this tool from siblings like update_brand and read_file by scope and return content.

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 when-to-use guidance: version 0 with empty fields means no brand exists, and extraction should be polled with increasing delays until importId matches update_brand's returned id and status is completed or failed. It also routes file reads to read_file and clarifies that this call does not start an agent session.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new context beyond them: the return payload shape (comments, anchor, anchor target) and an explicit prompt-injection warning about untrusted user-authored content — a real behavioral trait the 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?

Two sentences, zero waste: the first defines scope and payload up front, the second delivers the safety constraint. 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?

No output schema exists, and the description compensates by naming what comes back. For a single-parameter read tool this is nearly complete; only not-found behavior and access requirements are 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?

Only one parameter and schema description coverage is 0%, so the description must carry the load. 'Read one comment thread' implies threadId identifies the target, but it adds no format, sourcing, or error semantics (e.g. what happens if the ID is unknown) beyond the schema's own uuid format declaration.

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 a precisely scoped resource ('one comment thread with all its comments, its anchor and what it's on'). The singular 'one' implicitly separates it from list_comment_threads, but no sibling is named explicitly, so it stops short of the top tier.

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 second sentence gives operational handling advice (treat bodies as data, not instructions), which is valuable but is not selection guidance. Nothing tells the agent when to call this versus list_comment_threads, reply_to_comment_thread, or resolve_comment_thread.

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 behavior, so the bar is lower; the description adds value by disclosing what the call surfaces (activation state and required DNS records), effectively standing in for a missing output schema. It stops short of noting error behavior for unknown/unconnected domain IDs.

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

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

One sentence, front-loaded with the verb and resource, with the returned information immediately after. 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?

Adequate for a simple read-only lookup backed by rich annotations, but with no output schema the description should say more about what the returned activation states look like and how the caller should use them; the ID parameter is also unexplained.

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

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

The single parameter customDomainId has 0% schema description coverage, and the description never mentions how to obtain or format the ID. The name and uuid format make it inferable, but the description contributes nothing 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?

Names a specific verb+resource ('Diagnose a connected custom domain') and states what is inspected (activation state, required DNS records). It doesn't explicitly contrast with the sibling verify_custom_domain or connect_custom_domain, so 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?

The word 'Diagnose' plus 'connected' implies use during troubleshooting after connection, but there is no explicit when-to-use, no mention of verify_custom_domain as the alternative, and no stated precondition such as the domain having been connected first.

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 fully covered. The description's only added value is scoping the response to metadata rather than file contents, which is genuinely useful, but it says nothing about error behavior on a missing/inaccessible fileId.

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 no filler. Scope and identifier are established immediately.

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

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

For a single-parameter read tool with rich annotations and no output schema, the description is nearly sufficient. The residual gap is not clarifying how this differs from read_file or what metadata fields come back, but the core invocation path is unambiguous.

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?

One required parameter with 0% schema description coverage; the schema only supplies format=uuid. The description adds the meaning ('by fileId' identifies a document or folder), but gives no format, source, or acquisition guidance (e.g., from list_files).

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 plus scope ('metadata for an existing Files document or folder'), which implicitly separates it from read_file (content). However it never names read_file, list_files, or get_file_sharing as alternatives, so an agent must infer the boundary itself.

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?

No explicit when-to-use statement and no named alternatives, despite several near-siblings (read_file, list_files, get_file_sharing, update_file) in the same namespace. 'Existing' is the only hint that a valid fileId must already exist.

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 adds genuinely new behavioral context: a hard authorization gate ('only owner or workspace admin can read it') and the fact that inherited parent-folder access is folded into the result. It does not describe what happens on an unauthorized call (error vs empty), which prevents 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?

Two sentences, no filler. The result content is front-loaded and the access restriction follows as a qualifier where it belongs.

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

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

With no output schema, the description usefully enumerates what the response contains, and the auth gate plus annotations fully cover behavioral risk for a read-only tool. The only meaningful gap is the parameter's expected identifier format/scope, which is left entirely to a 0%-described 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?

The single fileId parameter has 0% schema description coverage, so the description must compensate. It partially does by establishing that the ID may refer to a document, folder, or artifact, but it never states the expected format (uuid) or whether a folder ID returns recursive children.

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 read verb ('See who can open') plus the exact resource and enumerates the four access dimensions returned: owner, team access, link, individual people, and inherited parent access. An agent can tell this is the read counterpart of set_file_sharing, though the sibling is never named, which keeps it short of a 5.

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

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

Usage is implied rather than prescribed: it says who is allowed to read sharing, but never says when to call this versus set_file_sharing (to modify) or get_file (for content). The precondition is useful, but the agent must infer the routing itself.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low, but the description adds the crucial behavioral fact that this returns the definition and not executed data. It also adds a directive to explain results to the user. Lacks detail on failure modes for an invalid ID or whether missing scope falls back to a default.

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

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

Four short sentences, front-loaded with the purpose and return contents, then usage, then the alternative-tool route. Every sentence carries information an agent needs to select or call the tool.

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

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

With no output schema, the description does its job by enumerating what the response contains and warning that it is a definition rather than data. The only omission is the meaning of projectId and any error behavior for an unresolved report ID.

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%: reportId is already documented in the schema, and the description largely repeats it (list_insights_reports / Insights URL). projectId is undocumented in both the schema and the description, a real gap the description does not compensate for. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read an existing report's definition') and enumerates exactly what is returned: formulas, SQL, data sources, permissions, resolved default scope. Explicitly distinguishes itself from the sibling query_insights_report, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use (need the report definition; ID comes from list_insights_reports or the Insights URL) and when-not-to-use ('Call query_insights_report for data'), naming the alternative directly. Nothing is left to inference.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, and the description adds substantial semantics on top: what needs_reconnect means versus a per-connection needsReconnect flag, the caveat that externalAnalytics only lists SQL views and is not proof metrics can be fetched, and what connectFailureMessage, isAlwaysAvailable, and isSettingsManaged represent. It also preempts a likely agent error by denying that the tool connects accounts or alters permissions.

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 status semantics are front-loaded and earn their space, but the middle section degenerates into a flat run of field notes (connectFailureMessage, isAlwaysAvailable, isSettingsManaged) with no structural separation from the workflow guidance. Every sentence carries content, yet the ordering would be easier to scan if return-field semantics were grouped together.

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

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

There is no output schema, so the description must carry return-value meaning itself, and it does so thoroughly for every field and status value an agent would encounter. Nothing material is missing for calling this two-parameter read tool correctly.

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

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

With 100% schema coverage the baseline is 3, and the description earns above that by enumerating supported analytics integration keys (triple-whale, contentsquare, intelligems, meta-marketing-api, google-analytics, google-search-console, shopify, converge), which tells the agent what values integrationKey actually accepts beyond the schema's "figma" or "shopify" examples.

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 first sentence names a specific verb and resource with scope ("Check one integration's connection status in the selected Replo project") and immediately enumerates the three possible outcomes. It also explicitly separates itself from the sibling connect_replo_account by stating "This tool does not connect an account or change permissions."

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 when-to-use conditions: before querying external metrics, when a provider's tools are absent from the catalog, and after the user connects an account ("when they say they're done, call this again"). It also states what to do with connectUrl in the user-facing flow, which is actionable routing guidance rather than a restatement of the 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?

Goes well past the annotations (which only cover read-only/idempotent/non-destructive) by disclosing that the customer contact address is masked, that no payment identifiers are returned, and that money values are minor-unit integers with Stripe-style examples for USD vs JPY plus the paired currencyCode. That is exactly the kind of output-shape and privacy context an agent cannot get from structured fields.

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

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

Three tight sentences: scope first, then the privacy limits, then the numeric encoding rule. No filler, and the most decision-relevant information (what record, what is hidden, how money is represented) is front-loaded.

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

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

For a single-parameter read with no output schema, the description covers return contents, data masking, and amount encoding thoroughly. It stops short of error/not-found behavior and the origin of the orderId, which an agent would still need to infer.

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

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

Schema description coverage is 0% and the single orderId parameter carries only type/format uuid, so the description must compensate. It says the tool takes "one storefront order" and references "the order's currencyCode," which hints at the identifier, but never states the expected format or where to source the ID. Partial compensation only.

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

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

States a specific verb ("Inspect") and resource ("the public record of one storefront order") plus the exact contents returned: line items, fulfillment, refunds, event history. The singular "one storefront order" implicitly separates it from the list-style sibling find_orders, though it never names that sibling explicitly.

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

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

There is no explicit when-to-use guidance: nothing says to call find_orders first to obtain an orderId, no prerequisites, and no note on what to do when the ID is unknown or the order is not found. Usage is only inferable from the purpose sentence, which is the definition of no guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered structurally. The description adds the substantive point that prices are monthly and tied to plan tiers, but says nothing about freshness of pricing or workspace scoping side effects; with annotations doing the heavy lifting, this is adequate rather than rich.

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 tightly packed sentence pair that front-loads the return scope before the usage conditions. Nothing is redundant, though the parenthetical feature list makes the opening clause dense enough to slow a first 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?

No output schema exists, so the description carries the burden of describing returns — and it does, naming currentPlan, tier prices, and per-tier Sightglass features. It stops short of stating whether pricing is static or account-specific, but an agent has enough to call and interpret it correctly.

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

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

There is one parameter with 100% schema description coverage, and the schema already tells the agent to source workspaceId from list_workspaces. The description contributes no additional constraint on the parameter, so the baseline 3 for fully documented schemas 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 precisely enumerates what the tool returns: the workspace's currentPlan, the Starter and Pro monthly prices, and which Sightglass capabilities each tier unlocks. That specificity clearly separates it from siblings like start_plan_upgrade, though it opens with a noun phrase rather than an explicit verb, leaving the 'get' framing implicit.

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

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

Three concrete activation triggers are given: a result names a locked field or higher plan, the user asks about upgrading, or the user reports a completed upgrade to confirm. There is no explicit exclusion or pointer to start_plan_upgrade as the action-taker, so the agent must infer the read-vs-mutate boundary from the sibling name alone.

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 meaningful context that this returns the public catalog view (not drafts/internal state) and only covers Replo-managed products, but says nothing about freshness guarantees, auth scope, or response shape.

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

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

A single front-loaded sentence with no filler; the qualifiers ("current", "public catalog") each carry meaning. It is well-sized for a simple getter, though it leaves no room for the disambiguation an agent would want.

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?

Wait-adjusted: for a one-parameter read-only getter with full annotation coverage and no output schema, the essential call decision (which product, read-only, idempotent) is conveyed. The remaining gap is return-shape detail, which is modest for a catalog-detail fetch.

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

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

Schema description coverage is 0%, so the schema only gives the type (uuid) and required flag for productId. The description contributes that the ID must identify a Replo-managed product, which narrows the valid domain, but adds no format, sourcing, or error semantics.

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 ("Retrieve") plus a scoped resource ("current public catalog details for a specific Replo-managed product"), which clearly separates it from find_products (search) and update_product (mutation). It does not name those siblings explicitly, so an agent still infers the boundary rather than being told.

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?

No statement of when to prefer this over find_products or get_order, and no prerequisites or failure conditions (e.g., what happens with an unknown or unpublished productId). The phrase "specific ... product" weakly implies a single-record lookup by ID, but usage is left to inference.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the description isn't carrying the safety burden. It still adds real domain behavior: the exact semantics of the checkoutProvider values ('shopify', 'replo', null) and the non-obvious trap that connecting Shopify does not flip the provider. It omits error/not-found behavior, keeping it from a 5.

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

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

Front-loaded with purpose, then the enum meanings, then the failure-mode caveat — every sentence is doing work. Slight redundancy between 'Check checkoutProvider before promising Shopify checkout' and 'connecting Shopify does not switch it' keeps it from a 5.

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

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

With no output schema, the description usefully enumerates the returned fields and disambiguates the one tricky value, which is exactly the burden it should carry. The one real hole is how to get projectId for a tool where it is the only required input.

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

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

Schema description coverage is 0%, so the description must explain projectId, and it does not — no mention of format (uuid), where to obtain it (likely list_projects), or what happens with an invalid id. Its field explanations describe the response, not the input.

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

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

States a specific verb and resource ('Read one Replo project's settings') and enumerates the returned fields, which implicitly separates it from list_projects and update_project. It does not explicitly name a sibling to distinguish from, 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 concrete trigger conditions: check checkoutProvider before promising Shopify checkout, or when a Shopify-connected site's Checkout button fails. No explicit when-not guidance or named alternatives (e.g., list_projects to discover projectId), so not a 5.

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

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

Annotations already provide critical behavior data like 'readOnlyHint' and 'idempotentHint.' The description adds valuable constraints by specifying the task type ('recurring Replo task'), providing context that helps narrow the scope of the tool's application beyond structural hints.

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

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

It is a single, extremely concise sentence that front-loads the function and purpose without unnecessary filler, achieving maximum information density.

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

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

Even without an output schema, the description is complete enough for the AI to understand the scope of the data retrieved (schedule and timing). It helps the agent determine if this tool matches the user intent perfectly.

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%, meaning the input parameters are already fully detailed in the structured schema. The description merely reinforces that the task ID must belong to a 'recurring' task, which adds very little semantic value over the structured data.

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 defines the action ('Inspect') and the resource ('recurring Replo task'). It also specifies exactly what aspect of the resource is being queried ('schedule and current timing'), making it highly specific.

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 stating it is for inspecting 'specific recurring Replo tasks,' naturally distinguishing it from broader list-tasks or deletion tasks in the sibling set. While it doesn't explicitly state 'don't use list_tasks', the context makes the differentiation 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), so the description earns credit for adding the prompt-injection caution that comment bodies are untrusted user content and must be treated as data, not instructions. 'With every comment' also implies a complete, unpaginated return, which is useful behavioral context not in 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?

Three tight sentences: purpose first, then the mutual-exclusion rule, then the security caveat. No padding, and the most decision-relevant constraint is front-loaded after the verb.

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 should explain what comes back; it partially does ('with every comment') but doesn't describe the thread/comment structure or ordering. Given 8 params with half schema-documented, the key calling constraint and safety guidance are covered, leaving only return-shape detail thin.

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

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

Schema coverage is only 50% across 8 params, so the description must compensate; it does by adding the 'exactly one of' mutual-exclusion constraint that the schema (all-optional, no oneOf) does not enforce. It leaves path and locale unaddressed, but their schema descriptions already explain 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 and resource ('List the comment threads') and enumerates the five parent entity types it can attach to, plus 'with every comment' to signal a full listing. An agent can distinguish it from get_comment_thread (singular fetch) by the plural scope, though the sibling is not 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?

Explicitly instructs 'Pass exactly one of fileId, folderId, siteId, orderId or assetId, and optionally status', giving concrete selection conditions. It does not compare against get_comment_thread or say when not to use the broad listing, so it stops 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered. The description adds genuinely useful scope context ('private working documents', 'separate media library'), but says nothing about pagination despite limit/cursor parameters existing, nor about ordering or result shape. With annotations doing the safety work, this is an adequate middle score.

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 no filler, and the most decision-relevant fact (project scoping, then My Files behavior) is front-loaded. Every clause earns its place.

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

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

For a list tool with five parameters, no output schema and no documented pagination contract, the description should at minimum explain how limit/cursor work together and what projectId is required for. Neither is addressed, so an agent cannot page correctly or interpret results from the definition 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 0% across five parameters, so the description carries the full burden and largely fails: it explains only parentId (and only its omission case), leaving projectId, kind, limit and cursor entirely undocumented. The enum for kind and the 100-item limit on limit are discoverable only by reading the raw 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 ('List private working documents and folders') and scopes it to a project. It also pre-emptively separates itself from the asset/media tools ('Assets are a separate media library'), so an agent can distinguish it from find_assets and upload_asset, though the distinction from siblings like get_file or read_file is left implicit.

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

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

It provides one concrete routing rule ('Omit parentId for My Files') and implies that media assets belong elsewhere, which is real when-to-use guidance. However, it never names the alternative tool (find_assets) nor says when not to use this tool, so the agent has to infer the rest.

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, so the safety profile is covered. The description adds genuinely non-structured behavior: page until the cursor is null and keep paging even after an empty page — a real trap avoided. It stops short of stating what a returned report record contains, so not a 5.

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

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

Four tight sentences, front-loaded with the resource and scope before the fallback guidance; nothing is padding. The 'nextOffset' mention is the only loose thread, since no such parameter is in 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?

With no output schema, the description carries more burden to explain return values, and it only hints at a cursor field without describing the report records themselves. It does cover the retrieval loop and the sibling routing well, but is partial for a 4-parameter discovery 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 description coverage is only 25% (only 'search' is documented), so the description needs to compensate and does not — limit, offset and projectId are never explained. Worse, the description references 'nextOffset' while the schema's parameter is 'offset', which risks confusing the agent about which field to feed back for pagination.

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 ('Discover ... Insights reports') plus the exact access scopes covered (private, team-shared, individually shared within a project). An agent can distinguish it from get_insights_report and query_insights_report without opening any schema.

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

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

Explicitly routes the agent: fall back to query_replo_analytics when no relevant saved report exists, use get_insights_report for definitions, query_insights_report for current results. This is a full when-to-use / when-to-use-something-else map naming the actual 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 annotations: explains pagination via next_cursor, and discloses the setup_required fallback response including eligible workspaces and steps to create a project. The annotations already cover read-only and idempotency; the description contributes the non-obvious edge behavior an agent could not infer.

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

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

Five tight sentences, front-loaded with purpose and usage, then edge behavior and pagination. 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?

Given three optional params, no output schema, and rich annotations, the description covers purpose, pagination, and the setup_required branch well. It omits detail on the shape of returned project objects and the limit/workspaceId semantics, which would complete the picture.

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

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

Schema description coverage is 0%, so the description must compensate; it maps cursor to 'next_cursor' follow-up and implies workspace scoping via 'within one workspace'. It doesn't document limit bounds or that workspaceId is a UUID filter, leaving some gap.

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

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

States a specific verb and resource ('List accessible Replo projects') with scope (optionally one workspace), and distinguishes it from siblings like get_project and list_workspaces by naming the resolution purpose. An agent can tell this apart from create_project and get_project without opening either schema.

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

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

Gives a clear when-to-use trigger: 'resolve the project for the user's Replo request'. It also states a negative boundary ('Listing does not create a project'), implicitly routing creation to create_project, but doesn't name that sibling explicitly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial beyond that: the returned fields (clone_url, is_default), pagination semantics (next_cursor/has_more), and a real correctness trap ('site names are dashboard labels, not SEO page titles'). This is genuinely useful behavioral 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?

Four tight sentences, purpose front-loaded, then defaults, then pagination, then the naming caveat. No filler; everything earns its place.

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

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

No output schema exists, so describing return fields and pagination is exactly what's needed, and it does that. It stops short of covering the `limit` parameter or what else a site object contains, leaving a small gap for a 3-param list 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 0%, so the description must carry parameter meaning. It explains cursor-driven paging implicitly via next_cursor and scopes the tool to a project, but never mentions the `limit` parameter or the required projectId's format. Partial compensation only.

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

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

States a specific verb ('Find the Replo site') plus resource and scope ('within a project'), with the intent triad 'inspect, manage, or clone'. An agent can tell it apart from create_site/update_site/list_projects, though it never names those siblings 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?

Gives concrete decision rules: use the site with is_default true when the user names none, and ask the user if no default exists. It also prescribes the pagination procedure before concluding a site is absent. Clear context, but no explicit routing to alternative tools (e.g. get_project).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description carries a lower burden. However, it adds nothing beyond them — no mention of pagination behavior, ordering, result size, or whether deleted/completed tasks appear.

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

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

One short, front-loaded sentence with zero filler. Its terseness is the source of the definition's gaps, but on the conciseness axis it is efficient and well-structured.

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

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

A paginated list tool with three parameters, no output schema, and no parameter descriptions needs more than one sentence. Pagination semantics and result-shape expectations are entirely missing.

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

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

Schema description coverage is 0%, so the description must compensate and does not: limit (1-100) and cursor are pagination parameters whose meaning and usage (e.g., how to page through results) are never explained. Only projectId's role is inferable from the sentence.

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

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

States a clear verb (List) and resource (scheduled Replo tasks) narrowed to a project scope. It does not distinguish itself from siblings like get_task or delete_task, but the core 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?

No indication of when to use this versus get_task, or when listing is preferable to fetching a specific task. The project-scope hint is implied by the required projectId but no explicit usage context or exclusions are given.

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, and the description adds meaningful workflow context beyond that: plan values returned, sign-in timing, single-vs-multiple workspace behavior, and downstream workspaceId propagation. It does not contradict any annotation.

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

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

The description front-loads the return content, then immediately explains when and how to use it. Every sentence carries actionable information 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?

For a parameterless, read-only listing tool with no output schema, the description provides enough detail about what is returned and how the resulting workspace id should be used. It is complete for the complexity of the operation.

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 input parameters, so there is no parameter meaning for the description to clarify. The baseline for a parameterless tool is 4, and the description appropriately focuses on return content and usage instead.

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

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

The description states the specific resource (the user's Replo workspaces) and what is returned alongside each one (its plan: free, starter, or pro). It is clear enough that an agent can distinguish this from sibling list tools for projects, sites, files, and tasks 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?

It gives explicit timing and branching guidance: call right after sign-in, use the only workspace if there is one, ask the user once if there are several, then pass the chosen id as workspaceId on Sightglass calls. It also states the alternative use case of switching workspaces.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds useful pipeline context (build, package, upload, deploy) that explains why the call is heavy and slow. It never spells out the actual risk implied by the destructive flag — that drafts become publicly visible and the change is not trivially reversible — nor whether the call is async or how long a deploy takes.

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

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

Three short sentences, front-loaded with the purpose, then the prerequisite, then the mechanics. No waste; the trailing fragment efficiently conveys the multi-stage deploy.

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

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

There is no output schema, and the description says nothing about what a successful publish returns (a job id, a URL, a status) or whether the agent must poll for completion. For a destructive, non-idempotent deploy operation, that leaves a real gap, though the parameter documentation compensates on the input side.

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 both parameters are documented in detail, including the omit-vs-empty-array semantics of promoteRoutes. The description only repeats the siteId sourcing already stated in the schema, adding no meaning beyond it; baseline 3 applies when the schema does the heavy lifting.

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

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

"Publish a site to make changes live" names a specific verb and resource, and the follow-up fragment clarifies that publishing is a build/deploy pipeline rather than a settings edit. It does not explicitly name a sibling to distinguish from (e.g. update_site, create_shared_preview), so it stops short of full 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?

The description gives one concrete prerequisite: the siteId comes from list_sites. There is no statement of when to publish versus alternatives such as create_shared_preview or update_site, and no guidance on exclusions or timing (e.g. publish after editing pages).

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), so the description's added value here is real: it discloses that individual query errors return alongside rows (partial failure), and that missing data is not treated as measured zero. Those are non-obvious behaviors an agent would otherwise misread as clean zero-metrics. No return-shape detail beyond "structured rows," but annotations lift the burden.

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

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

Six short sentences, no waste: identity first, then override behavior, then return shape, then the data-integrity caveat, then the follow-on tool. Each sentence carries distinct information and the most decision-relevant constraints (non-mutation, one-call orchestration) are surfaced early.

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

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

For a nested-schema, no-output-schema read tool this covers what an agent needs: what runs, how to override, what comes back including errors, and what not to assume about missing data. A minor gap is that it doesn't hint at the 30-query cap or the row grain (dimensions vs metrics), both left entirely to the schema.

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

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

The description names the four override dimensions (dates, comparison, filters, breakdown), mapping them onto the nested scope object, and the schema itself carries a description for scope plus queryIds/reportId. With 75% coverage the schema does most of the work, but the sentence "Optionally override..." correctly signals overrides are additive-to-defaults rather than required.

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 ("Execute saved report queries") and pins the semantics to the Insights UI's own formula and scope compiler. It then explicitly disclaims what the tool does NOT do ("Reading or querying does not create a report or artifact"), which separates it from create_artifact and implies separation from get_insights_report/list_insights_reports.

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 downstream routing: check integration status for external sources, use results to answer questions, or create_artifact to persist. What's missing is an explicit pointer to the sibling that fetches the report definition/query IDs (get_insights_report) versus when to use query_replo_analytics instead — the agent has to infer those from sibling names.

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 what readOnlyHint/idempotentHint already declare: SELECT/WITH-only enforcement, server-side project scoping including sibling authorization, a 60s execution cap, a 100k row cap, an 8-hour external-metric cache, a 10,000-row provider report cap, and the crucial warning that an empty external result does not prove zero activity. These are exactly the failure modes an agent would otherwise misreport.

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 and logically ordered — purpose, then usage, then constraints, then the integration caveat. But the enumeration of thirteen queryable tables in the top-level prose is largely duplicated by the schema's table listing and DDL, and the same caching/row-cap facts appear twice, so some sentences do not fully earn their place.

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

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

For a raw-SQL tool with no output schema and only two parameters, this is comprehensive: dialect, allowed statement types, scoping rules, aggregate-state merge-function requirements, timeouts, row caps, caching, and where table columns are documented. An agent has enough to construct a valid query and interpret an empty result correctly.

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

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

The description explains that project scoping is enforced server-side and must not be filtered manually, which gives projectId real operational meaning beyond the schema's bare uuid format. The query parameter's semantics are covered exhaustively in the schema itself, so the prose adds caveats rather than duplicating it, though projectId's own semantics are only implied.

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

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

Opens with a specific verb and resource — 'Run read-only ClickHouse SQL over a project's Replo analytics' — and scopes the subject matter to traffic, conversion, revenue and session-level questions. It explicitly differentiates from the sibling Insights tools (get_insights_report, list_insights_reports) by stating no saved report is required, so an agent can pick between them without opening a schema.

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

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

Gives explicit selection criteria: use for ad hoc questions or when list_insights_reports finds no relevant report, and pre-empts the wrong inference with 'an empty report list does not mean analytics are unavailable.' It also names prerequisites (call get_integration_status first) and hands off provider-native discovery to provider tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety needs no restating. The description adds genuinely new context: reads are 'complete' (not truncated) for small files, and large or binary files return a 'temporary' URL, signaling expiry and out-of-band retrieval. It stops short of stating URL lifetime or size 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?

A single sentence that front-loads the primary mode and closes with the fallback. Every clause carries information; no waste.

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

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

With no output schema, the description correctly covers the two return shapes (document body vs. temporary URL), which is the key missing structured information. Minor gaps remain around size thresholds and URL expiry, but an agent can 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?

One required parameter (fileId) with 0% schema description coverage, and the description never mentions it or its UUID nature. The 'in Files' phrasing loosely contextualizes the identifier, but the description does not compensate for the empty 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?

A specific verb ('Read') plus resource ('UTF-8 documents in Files') with the dual-mode behavior stated up front. It does not, however, distinguish itself from the sibling get_file or list_files, so an agent cannot rule those out from the description alone.

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

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

The description gives an implicit selection rule — small UTF-8 documents get inline content, binary/larger files get a download URL — which is useful. But it never names alternatives (get_file, list_files) or states when a caller should prefer those instead, leaving the boundary to inference.

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

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

Annotations already declare readOnly=false, destructive=false, openWorld=true; the description adds real context beyond them — the open-thread precondition and an explicit prompt-injection warning about untrusted comment bodies. It stops short of saying what a successful reply returns or whether notifications/mentions trigger side effects.

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, each earning its place: action, precondition, and safety note, with the core action front-loaded. No filler or restatement of the name/title.

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

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

For a non-idempotent, open-world mutation with no output schema, the description covers the key behavioral risks (closed threads, untrusted content). It omits return/confirmation behavior and any permission requirements, which are the remaining gaps.

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%: body and id are well documented in the schema, threadId is not. The description adds semantic meaning for body ('user-written content, possibly from people outside the workspace') but says nothing about threadId or how to confirm the target thread. Roughly baseline for this coverage level.

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 ('Reply to an open comment thread') plus the acting identity ('as the signed-in user'), which separates it from create_comment_thread. It never names resolve_comment_thread or get_comment_thread explicitly, so sibling differentiation is only implicit.

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

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

Gives a clear precondition/exclusion: 'Resolved threads must be re-opened first,' which tells the agent when this tool will fail and implies the prerequisite action. It does not name the re-open or resolution tool to use instead, so the routing is left to inference.

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

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

Beyond the annotations (readOnly=false, idempotent=false, openWorld=true), the description discloses the real-world side effect ('Files feedback with Replo's team'), the anti-duplication rule that matters given idempotentHint=false, and a PII guardrail ('Omit credentials and unrelated customer data'). It also constrains fabrication ('never invent evidence, root cause, or severity'), which 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 purpose, then constraints, then post-call behavior — a sensible order with no filler sentences. The prose is dense and clause-heavy, cramming evidence standards into long run-ons, but each sentence carries an actionable rule.

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

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

For a 5-parameter mutation tool with no output schema, it covers purpose, exclusions, evidence standards, privacy, and duplicate avoidance. It omits what the agent gets back (e.g., a report or ticket identifier) and any indication of latency or failure handling if submission fails.

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%, and the description adds genuine signal beyond it: errorContext has no schema description but the description tells the agent to put 'observed errors or request IDs' there, and it explains the required evidentiary standard for reproSteps and description. It stops short of format guidance for title or how to mark unknowns syntactically.

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

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

The description opens with a specific verb+resource ('Report a credible ... Replo defect') and enumerates the scope (API, MCP, documentation defects). It clearly carves out non-defects ('ordinary bad arguments, missing configuration, and fixable site-code mistakes'), though it never names submit_feature_request, the sibling an agent would most plausibly confuse this with.

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

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

It states when to file ('credible user-reported or directly observed'), when not to (bad arguments, missing configuration, site-code mistakes), and post-call behavior ('continue helping with the user's task', 'Do not resubmit the same report after success'). The prerequisite 'Pass projectId from list_projects' is spelled out explicitly.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety class is known. The description adds concrete consequence ('which can then overwrite or delete content, publish, or write to an external service') and the failure behavior for a non-pending interaction, though it leaves non-idempotency implicit.

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

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

Front-loaded with the core action, then branches by type, then consequences, then failure mode. Sentences are dense but every one carries distinct information; nothing is redundant with 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?

No output schema exists, and the description covers the return ('updated session status') and the error case for stale interactions. Combined with the rich parameter guidance, an agent has everything needed to call it correctly in one attempt.

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 schema coverage at 80%, the description still adds real meaning: answers are one array per form step in order, an empty array skips a step, custom text is allowed only where that step's allowCustom is true, and decision comes from response options. The schema alone would not convey the ordering/skip semantics.

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 ('Resolve one pending Replo agent interaction') and scopes it to a single pending interaction with the user's explicit answer. An agent can separate it from get_agent_session or abort_agent_session without opening any schema.

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

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

Gives explicit branches: permission requests take type=permission plus the decision; questions take type=question plus one answers array per form step. It also states an exclusion ('Never infer an answer') and a recovery path ('call get_agent_session again') when the interaction is stale.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered without description help. The description adds the re-open semantics and a scoping etiquette rule, but says nothing about what resolving actually does (notifications, thread visibility, failure mode when threadId is unknown).

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, the primary operation is front-loaded, and the re-open escape hatch follows immediately. No filler or hedging to strip.

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

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

For a two-parameter idempotent mutation with no output schema, the definition is adequate but thin – it omits the return value and what state change the caller should expect. Annotations and the trivial schema carry most of the load, so the remaining gap is real but modest.

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% – `resolved` is documented in schema and the description only restates it, while `threadId` (a uuid) carries no description in either place. The description implies threadId identifies an existing thread but adds no lookup or error semantics, so it neither compensates for the gap nor ignores it.

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

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

States a specific verb+resource ('Resolve a comment thread') and covers the inverse operation explicitly ('pass resolved: false to re-open it'). Clearly distinguishable from siblings like get_comment_thread, reply_to_comment_thread, and list_comment_threads.

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

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

Gives a concrete selection rule: 'Resolve only threads the user asked about or that you addressed' – that is a real when-to-use constraint, not just restatement. It falls short of 5 because it never names the sibling alternatives (reply_to_comment_thread, get_comment_thread) for the cases where resolving is wrong.

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

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

Goes well beyond the annotations by disclosing the blast radius ('page content is preserved' — only the link is destroyed) and the authorization model. It also confirms the idempotent behavior announced in annotations ('Repeating the request succeeds'), so an agent knows retries are safe and that the destructiveHint is scoped to the link only.

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

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

Four short sentences, front-loaded with the action, then permissions, then idempotency/scope, then a safety guardrail. No filler and no repetition of schema or annotation content.

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

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

Covers purpose, auth, idempotency and side effects for a one-parameter tool, which is nearly everything an agent needs. With no output schema present, the description never states what a successful response returns, which is the only remaining gap.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does identify the provenance of sharedPreviewId ('the id returned by create_shared_preview'). It does not restate the UUID format or validate the value, but the critical question — where to get the id — is answered.

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 ('Disable') and resource ('a public shared preview link'), and ties the tool to its sibling create_shared_preview as the source of the id. An agent can immediately distinguish this from creation/listing siblings without opening the schema.

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

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

Explicitly names who may call it (creator with current project access, or a workspace admin) and adds a scoping instruction: 'Revoke only the link the user requested.' It does not enumerate when *not* to use it or name an alternative, but the usage context is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the caller context (invoked by the artifact card) but says nothing about caching behaviour, which the forceRefresh parameter hints matters, or about what the call 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?

Two short sentences, caller-context first and the routing warning second. Every clause carries information and 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?

For a tool the description says not to call directly, this is close to sufficient, and the nested scope object is fully documented in the schema. What is still missing is any note on return shape or on when cached versus refreshed results are returned, which matters given forceRefresh.

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 parameters like fileId, chartPath and queryId are already documented with disambiguation notes in the schema itself. The description adds no parameter-level meaning beyond that, so the baseline applies.

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

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

States a specific verb and resource ('load the live numbers for a chart or report') and ties it to the artifact card. It does not spell out what the returned data looks like, but the action is unambiguous and distinguishable from the sibling it names.

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 'Not for direct use' and redirects to the alternative: 'call query_insights_report to query a report.' That is a clear when-not plus a named substitute, leaving no inference 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?

Goes well beyond the annotations: it discloses the permission requirement, that "link" publishes the file to anyone with the URL, that null revokes, that parent-folder inherited access survives, that unlisted audiences are untouched, that the write is all-or-nothing, and what the response contains (post-change access plus artifactUrl). That is exactly the destructive/mutation context an agent needs despite destructiveHint=true already being set.

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 permission, then the audience model, then edge cases, then return value — a logical order with no filler. It is dense, packing multiple concepts into single sentences (e.g. the final sentence bundling the return shape with artifactUrl), 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?

No output schema exists, yet the description explains the return value; no annotations need supplementing on permissions or blast radius, and the inheritance/atomicity semantics answer the questions an agent would otherwise have to guess at. Nothing material is missing for correct 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 coverage is only 50% (fileId has no description), but the description compensates strongly for the complex access array: audience kinds, allowed roles per kind, null-removal semantics, once-per-audience constraint, and unlisted-audience behavior. The one gap is that fileId is never described or tied to list_files/get_file output.

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: "Change who can open a Files document, folder, or artifact." This cleanly separates it from the read-side sibling get_file_sharing and from content tools like update_file, and the three supported resource types are 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?

Gives the authorization precondition up front ("Only its owner or a workspace admin can") and explains the additive/patch semantics (unlisted audiences keep access, null removes). It stops short of explicitly routing the agent to get_file_sharing to inspect current sharing first or naming any alternative.

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 real context beyond the annotations: available is absolute rather than a delta, trackInventory without available leaves a variant unsellable, and POD/digital variants are rejected. What it omits is equally important for a destructiveHint=true tool: whether variants not listed in the array are left alone or wiped.

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

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

Four tight sentences, front-loaded with what the tool does, then the two operational traps. No filler, no restating of the title or schema types.

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 mutation with no output schema, it covers the important failure modes (refusals, unsellable state) but not the replacement semantics of the variants array. An agent still cannot tell whether omitting a variant clears its stock, which matters before invoking a destructive 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 0%, so the description must carry the load, and it does for the hardest fields: optionValues semantics (empty array for no-option products) and available as an absolute count. It leaves continueSellingWhenOutOfStock and the 1–250 variants bound unaddressed, but the core addressing model is explained.

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: setting stock counts and stock policy for a Replo-managed product's variants. The variant-addressing scheme (option-value combination) makes the scope precise. It does not explicitly contrast with the sibling update_product, which an agent might reasonably confuse with this tool, so it falls short of a 5.

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

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

Gives a clear when-not rule: only merchant-fulfilled products can track stock, and print-on-demand/digital variants will be refused. It also warns to set trackInventory and available together. It does not name an alternative tool for the refused cases, so there is no explicit routing to a sibling.

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 states that nothing about the artifact changes, lists what is returned (title, description, viewer link), and discloses host-dependent rendering with an explicit fallback: hand the user the artifactUrl where no card appears. It also tells the agent how to respond afterward (summarize in a sentence, don't repeat contents), which the 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?

Purpose and call cadence are front-loaded, and each subsequent sentence covers a distinct operational point (triggers, return value, card-present behavior, card-absent behavior). It is a bit long for a one-parameter read tool, but no sentence 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 no output schema, the description supplies the return shape itself, and it explains the conditional UI outcome an agent must reason about. Nothing needed to invoke or follow up on this tool is missing.

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

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

Schema coverage is 100% and the single fileId parameter is already documented in detail, including the warning not to pass an embedded report file ID. The description adds no parameter-level meaning of its own, 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 opening clause pairs a specific verb and resource ("Show a saved artifact") with the concrete mechanism ("inline card they can expand and scroll") and even the host condition. This clearly separates it from siblings like get_file, read_file, and get_artifact_report_context, which fetch data rather than render a user-visible card.

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 enumerates the exact triggering conditions: after create_artifact or update_artifact saves one, after generate_artifact's session reports a saved artifact, or when the user asks to see an existing one. It also constrains frequency ("Call it once"), which prevents duplicate calls, and names the sibling tools that precede 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?

Annotations already establish read-only/idempotent/non-destructive, and the description adds substantial context beyond them: nothing is rendered to the user until sightglass_show is called, the show call does not re-search, plan-gated fields come back null and are listed in `locked`, and the agent is told never to estimate locked data. These are exactly the behavioral constraints an agent needs and cannot infer from the schema.

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

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

Purpose is front-loaded in the first sentence and the operational constraints follow in a sensible order. It is dense and long for a single paragraph, with mild redundancy between 'Returns data only: nothing is shown to the user yet' and the later show-call instruction, but nearly every clause carries real information.

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

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

With no output schema, the description still fully describes the return: a 0-100 position per axis, raw similarity, `isYou` marking, null/locked fields, and `lockedCount`. Combined with the parameter and follow-up guidance, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining semantics the schema cannot: axes override lens, omitting `high` auto-derives the opposite, the user's own company and Brand Studio personas are always included and flagged isYou, and `companyRefs` omitted means top companies with the project's own company force-added.

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 concrete verb-plus-resource ('Place personas, ads, landing pages or companies on one or two "this vs that" axes') and specifies the output shape (0-100 position per axis plus raw similarity), which is far more than the title 'Compare on a map' conveys. It does not name a near sibling such as sightglass_get_rankings or sightglass_find_personas to say how this differs, so it lands just shy 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?

It gives explicit use cases ('where do we sit against these brands', 'which buyers are nobody's focus') and explains the axes-vs-lens choice, plus the mandatory follow-up: 'Once you know the answer, call sightglass_show once with this call's resultId'. What is missing is a when-not-to-use signal, e.g. when to prefer sightglass_get_rankings instead.

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 idempotentHint=true and destructiveHint=false, and the description reinforces this with a concrete consequence: 'copying the same creative again returns the existing asset.' It also discloses the return payload (asset id and URL), which the annotations do not. It omits any mention of permissions or plan implications, which are instead buried in the schema fields.

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

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

Three tight sentences: what it does, the critical parameter caveat, and the return/idempotency behavior. Every sentence earns its place and the core action is front-loaded.

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

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

For a three-parameter, single-purpose copy tool with no output schema, the description covers the action, the source-to-destination flow, the id-caveat, and the return shape. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented in detail, including the workspace-plan behavior and the creative.id caveat. The description only restates the creative.id constraint, adding no syntax, format, or precedence information beyond what the schema provides. 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 gives a specific verb and resource ('Copy one ad creative's image from Sightglass into the Replo project's Assets') plus a clear motive ('so it can be used as a reference'). It implicitly separates itself from upload_asset by naming the Sightglass source, but never explicitly contrasts with the closest 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?

The stated purpose ('used as a reference in the project') supplies the condition for choosing this tool, and the note about using `creative.id` rather than the ad id preempts a common misuse. It stops short of naming alternatives such as upload_asset or find_assets, so there is no explicit when-not guidance.

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

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

Annotations already declare the write, non-idempotent, non-destructive, closed-world profile. The description adds the return value ('returns the board and its id'), which matters since there is no output schema, but it says nothing about name uniqueness, what happens if the same name is created twice, or how workspace/plan selection affects the call.

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

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

Three short sentences with the core action front-loaded and no filler. The kind enumeration partially restates the schema enum, though the parenthetical glosses justify its inclusion.

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

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

For a simple create tool with safety annotations, this covers action, board semantics, allowed kinds, and return value. It falls short only on edge cases such as duplicate names and workspace prerequisites that the schema mentions but the description does not reinforce.

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% and the enum for 'kind' is already documented, so the schema does most of the work. The description's glosses ('site_page (landing pages)', 'company (brands)') add modest meaning beyond the bare enum values but nothing about name constraints or the workspace/project 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?

States a specific verb and resource ('Create a named board in the user's Sightglass collection') and clarifies what a board contains, which no sibling name conveys. It does not explicitly contrast with sightglass_update_board or sightglass_delete_board, but the verb makes the distinction obvious.

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

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

There is no explicit when-to-use guidance, no mention of when to prefer sightglass_update_board, and no note on when workspaceId/projectId must be supplied. The description implies creation within a user's collection but leaves selection conditions to inference.

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