Replo

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 partly covered. The description goes beyond them by stating the concrete consequences: unfinished work is interrupted, partial changes may remain, completed changes are NOT rolled back, and the session itself is retained. That 'what survives and what persists' detail is exactly the context an agent needs before calling a destructive tool.

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

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

Three short sentences, no filler, with the core action front-loaded and the consequences following immediately. Every clause 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 single-parameter cancellation tool with no output schema, the description covers the action, its side effects, and session persistence reasonably well. It omits what the caller receives back and whether a subsequent call to another tool is needed to resume or clean up.

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 description never mentions sessionId. The schema constrains the value to a UUID and names it, so the intent is inferable from the tool purpose, but the description does not compensate for the coverage gap by explaining which session to target (e.g., the active vs. any historical session).

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: 'Cancel the in-progress turn of a Replo session.' An agent can distinguish this from the read-oriented get_agent_session and the interaction-oriented resolve_agent_interaction without opening a schema. It stops short of explicitly naming a sibling for contrast.

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 'in-progress turn' — the tool is for interrupting a running turn — but there is no explicit when-to-use statement, no exclusions, and no pointer to alternatives such as resolve_agent_interaction for sessions waiting on input. The agent must infer the trigger condition.

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

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

Annotations already flag this as a non-read-only, destructive, non-idempotent, open-world mutation. On top of that the description discloses that the operation is asynchronous and must be polled, that source edits may run in preview, and that corrections reuse the original sessionId. That is substantial behavior beyond the structured hints.

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

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

Purpose and scope are front-loaded, then prerequisites, then lifecycle, then the publish caveat — a sensible ordering. It is on the long side, and the closing sentence about the Replo agent using its normal tools is contextually useful but the least load-bearing.

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 async, destructive, multi-session operation with no output schema, the description covers everything an agent needs: prerequisite brand kit and site state, how to start, how to poll, how to correct, and that publishing is a separate step.

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 adds operational meaning the schema only implies: that omitting sessionId starts an operation, that a correction pass must target the same unchanged site, and that the agent implements via its own tools and integrations. Modest but real value above the schema text.

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

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

Opens with a specific verb (apply) plus a precise resource set (shared style tokens, fonts, layout, shared components) scoped to a single site's drafts. It explicitly contrasts itself with the saved brand kit, so an agent can separate it from create_or_update_brand_kit and get_brand_kit without reading either schema.

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

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

States the prerequisite (provisioned site, and create_or_update_brand_kit first if no saved brand), the follow-up (poll get_agent_session), the continuation path (same tool with sessionId and unchanged target), and the exclusion (publish_site separately to go public). This is a full when/when-not/alternative map.

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, openWorld=true and idempotent=false, so the agent knows this is a mutating, non-idempotent call. The description adds substantive context beyond that: the created domain is pending, DNS records are returned, verification must occur before activation, and there is a critical constraint against using a Shopify primary domain. This is genuinely helpful behavioral disclosure.

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, zero padding, with the core action and its outcome front-loaded and the safety warning placed last for emphasis. 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?

With no output schema, the description usefully explains the return value (DNS records) and the pending/verification lifecycle, which is what an agent needs to proceed. It omits behavior on duplicate/repeat calls (notably with idempotentHint=false) and any permission prerequisites, leaving minor 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 description coverage is 0% for both parameters, so the description carries the burden. It implies siteId identifies 'a Replo site' and that domain is a custom domain requiring DNS records, but it gives no field-level meaning, format expectations, or the Shopify-domain constraint tied specifically to the domain argument. 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+resource ('Begin connecting a custom domain to a Replo site') and clarifies scope ('This creates a pending domain'), which distinguishes it from the sibling verify_custom_domain and get_custom_domain_status. An agent can identify the tool and its role in the domain lifecycle without opening the schema.

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

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

The description places the tool as the first step ('Begin...') in a sequence leading to verification, and gives an explicit when-not: 'Never connect a Shopify store's primary domain.' It does not name the follow-up tools (verify_custom_domain, get_custom_domain_status) that would complete the routing guidance, so it falls short of a full 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds traits the annotations don't capture: it opens the client's sign-in window (a visible UI side effect) and returns the user's identity. It stops short of describing decline/failure handling, so not a full 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 action is front-loaded in the first clause, followed by the precondition, the side effect, and the follow-up call. Every clause carries distinct 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?

With no parameters and no output schema, the description still tells the agent what triggers the call, what side effect to expect, and what the return conveys ("returns who they are"). Nothing needed 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?

The tool takes zero parameters, so parameter semantics is trivially satisfied and the baseline is 4. There is nothing for the description to disambiguate.

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 ("Sign the user in to Replo") and is immediately distinguishable from siblings like connect_custom_domain or get_integration_status, which are domain/status operations rather than authentication. An agent can tell this is the sign-in/auth tool without opening the schema.

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

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

Gives an explicit precondition ("only after the user agrees to connect an account") and a concrete trigger ("usually after a tool returned status sign_in_required"). It also routes the agent forward with "Then call list_workspaces", so both when and what-next are covered.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing that the secret is returned once, that it must not be repeated in chat or committed, that the key grants no publishing or workspace-admin access, and that project-management permission is required. The only missing piece is whether keys can be revoked later or how many can exist, which keeps it just short of a 5.

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

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

Purpose is front-loaded in the first clause, followed by scope defaults, access limits, secret-handling warning, and ID-resolution hints in that order. Five sentences, each adding distinct operational 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?

With four parameters, no output schema, and sparse annotations, the description covers everything an agent needs: what it creates, scoping rules, prerequisites, what is returned (the secret, once), how to store it, and how to resolve the required IDs.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does explain the scopes parameter's default and meaning, and tells how to obtain workspaceId/projectId (list_projects) and the clone URL (list_sites). However the required `name` parameter is never addressed, and none of the UUID formats or length constraints are echoed.

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 (create an API key) and narrows scope precisely: local Git development of one Replo project at git.replo.app. An agent can immediately distinguish this from create_project, create_site_page, or other create_* 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?

Explicitly says to default to repo.read for cloning/pulling and to include repo.write only for authorized pushes, and it names prerequisites (permission to manage the selected project) plus the exact sibling tools to call first: list_projects for IDs and list_sites for the clone URL.

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 non-read-only, non-destructive, non-idempotent profile, so the bar is lower. The description adds real behavior beyond that: name conflicts never overwrite (which explains the non-idempotent/write semantics), and asset sources are copied without deleting the source.

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, each earning its place: the create action, the source requirement, the asset-copy behavior, and the conflict rule. Front-loaded with the core action.

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 write tool with no output schema and thin schema coverage, the description covers the source variants and the key mutation behaviors an agent needs. Remaining gaps — return value and how a name conflict is resolved (error vs. rename) — are minor.

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

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

Schema coverage is only 20%, so the description must compensate, and it partially does — it clarifies that source is required for files, describes the three source forms (text, base64, asset), and that folders omit source. It says nothing about projectId or parentId, leaving those 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+resource with scope ("Create a private document or folder in Files"), immediately distinguishing documents from folders. It does not name a sibling (e.g., update_file, upload_asset) to route against, so it stops short of 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?

Provides conditional guidance about source types (documents require a source, folders do not) which is genuinely useful. However, it never says when to use this tool versus upload_asset, update_file, or find_assets — the sibling set that most overlaps with creation.

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

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

Annotations declare destructive=true and non-idempotent, and the description meaningfully elaborates on that by warning that replacement can delete prior brand data and pull in assets/references. It also discloses the asynchronous agent-session lifecycle and the required confirmation step, which annotations alone cannot convey. It stops short of stating permission/auth requirements, 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?

Three tightly packed sentences with no filler: the core action leads, then scope of content, then the destructive/async caveats and the sibling exclusion. Every sentence earns its place and the routing information is front-loaded after the primary purpose.

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, asynchronous, open-world mutation with no output schema, the description supplies exactly what an agent needs: that a session must be polled, that a confirmation must be answered, that data may be deleted, and which sibling handles the restyle/publish follow-up. Nothing required to invoke it safely 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 67%: projectId and sessionId are structurally documented, and sessionId's continue-vs-start semantics plus instructions' constraints live in the schema descriptions. The tool description adds the list of brand content fields but gives no extra meaning for projectId, sessionId, or the instructions format beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb pair and resource (create or update the project's saved brand) and enumerates the content domains covered (business info, colors, fonts, logos, personas, overviews, file tags). It explicitly carves itself off from apply_brand_kit_to_site, so an agent can distinguish it from siblings without opening a schema.

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

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

Gives explicit routing ('Does not restyle or publish a site: use apply_brand_kit_to_site separately'), describes the import-from-URL case, and prescribes the follow-up workflow (poll get_agent_session and answer the replacement confirmation). When-to-use and when-not-to-use are both covered.

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

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

Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds one genuinely useful behavioral fact beyond them: 'New products are active immediately.' It does not disclose permissions, duplicate-handling, or what a 'Replo-managed' product constrains.

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

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

Two tight sentences with no filler, and the core purpose is front-loaded. It is well-sized for the tool, just light on substance rather than padded.

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

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

For a 5-parameter creation tool with no output schema and 0% parameter documentation, the description omits far too much: no parameter meaning, no required-field guidance, no indication of what is returned or how failures surface. It covers purpose and activation only.

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 5 parameters (projectId, title, slug, description, externalCheckoutUrl) and the description names none of them. Unlike the zero-parameter baseline, this tool needs description-side compensation that it does not provide, so the agent gets title/projectId semantics only from 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+resource ('Create a ... product') and qualifies it as 'Replo-managed ... for native product pages or checkout flows', which separates it from get_product/find_products/update_product. It does not name a sibling explicitly, but the create scope is unambiguous.

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

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

No when-to-use or when-not-to-use guidance. It never mentions prerequisites, nor when to prefer update_product or find_products first. Implied usage only — that it is the creation path — with nothing to steer the agent.

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 safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds value beyond them by disclosing the side effect ('this changes the workspace's project list') and the return behavior ('Returns the created project'). No contradiction with the non-readOnly, non-idempotent hints.

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

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

Three tight sentences, front-loaded with the action, then prerequisites, then the effect and return. Every sentence earns its place with no redundancy.

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-param create tool with annotations covering the safety profile and no output schema, the description supplies what is missing: the workspaceId source, the side effect, and the return. Only minor gaps remain (workspace eligibility criteria, name constraints).

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does name both params and their intent: workspaceId (must be eligible, sourced from list_projects) and name (project name). It omits format constraints like the UUID pattern and the 256-char name cap, but the essential meaning of each parameter is conveyed.

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

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

States a specific verb and resource ('Create a Replo project') with the scope of where it lands ('in a workspace'). This is clearly distinguishable from get_project/update_project/list_projects by the verb alone, though it never names a sibling to sharpen the contrast.

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 key prerequisite and routes the agent to the right source: 'Requires an eligible workspaceId from list_projects.' That is real when-to-use guidance. It stops short of stating when not to use it (e.g., when the project already exists, use get_project/update_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 idempotentHint=true, destructiveHint=false, and openWorldHint=true; the description reinforces this with 'create or recover' (idempotency) and adds non-obvious context that anyone with the URL can view the draft and that availability is checked at open time. It stops short of describing return payload or link persistence, but the annotation coverage lowers the bar.

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 sentences, front-loaded with the core operation followed by identifier sourcing, locale default, and safety caveats. Dense but each sentence carries a distinct instruction; slightly long for the operation but not wasteful.

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

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

No output schema exists, so the description would ideally hint at what a caller receives (a URL). It comes close via 'create or recover a public live preview link' and notes the availability-check behavior, but does not state the returned link shape. Otherwise complete for a 4-param tool with an open-world annotation.

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% – route and locale are documented in the schema, but siteId and projectId have no schema descriptions. The description compensates by naming where each ID comes from (list_projects, list_sites) and giving route/locale usage rules, adding genuine meaning beyond the structured fields.

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 or recover a public live preview link to a site page without publishing.' The 'without publishing' clause cleanly distinguishes it from publish_site and its inverse revoke_shared_preview in the sibling set.

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

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

Explicitly names the source tools for identifiers (list_projects, list_sites), tells when to omit locale, and adds a clear behavioral rule: 'Share only when requested; if the preview workspace is missing, report that state without editing or publishing the site.' This covers when-to-use and the fallback case.

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

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

Annotations declare destructive/openWorld/non-idempotent/not-readonly, and the description adds substantial context beyond them: it starts an asynchronous internal-agent operation requiring polling, it requires a provisioned site, and source edits may execute in its preview. These are meaningful operational traits the agent cannot get from annotations alone.

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 sentences, front-loaded with the core action and target before moving to async behavior and corrections. Dense but every sentence carries distinct information; only mild tightening would help.

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

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

With no output schema, the description compensates by naming the async completion path (poll get_agent_session) and the separate publish step. For a destructive, open-world creation tool with 4 params, this covers the operational prerequisites and lifecycle an agent needs.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds real value on top: it explains what the instructions content should contain (copy, layout, product references, design requirements) and what to exclude (conversation history, credentials), plus the sessionId continuation semantics. It stops short of detailing the route pattern, which the schema handles.

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

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

States a specific verb+resource with scope ('Create a draft page at one route in an existing site') and clarifies it preserves existing pages. It does not explicitly distinguish itself from the sibling edit_site_page or delete_site_page, which an agent must infer from the verb 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?

Gives explicit when-to-use conditions (provisioned site required), names the follow-up tool for going public (publish_site), and routes corrections back to this same tool with sessionId and unchanged target. The polling alternative get_agent_session is named for the async result. Nothing 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 mark this destructive and non-idempotent, and the description adds substantial context beyond them: the published copy stays live until a separate publication, sibling routes are untouched, the operation is asynchronous and must be polled via get_agent_session, source edits may execute in its preview, and the agent may use connected integrations. That is real behavioral disclosure, not a restatement of the 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?

The critical constraints (what is removed, what survives, async polling) are front-loaded, which is good. However the tail sentence about the Replo agent using its normal tools and integrations is generic boilerplate that does not help an agent decide or invoke, and the description sprawls across eight sentences.

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 async, destructive, session-based mutation with no output schema, the description covers everything needed: prerequisite (provisioned site), return-handling (poll get_agent_session), correction flow, blast radius, and the separate publish step. Nothing an agent needs to invoke 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 baseline is 3, but the description adds usage semantics the schema only implies: the sessionId is for continuing/correcting an operation and must target the same route. The instructions parameter's content restrictions are already fully covered by the schema.

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

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

States a specific verb and resource ('Remove the selected route's draft page') and immediately bounds scope by negation: it does not delete the site or other routes, and it does not publish. An agent can separate this from edit_site_page, create_site_page, and publish_site without opening a schema.

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

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

Gives explicit routing guidance: use publish_site separately to make changes public, requires a provisioned site, and describes the correction path (re-call with sessionId and unchanged target). It stops short of explicitly contrasting with edit_site_page for the 'change rather than remove' case, so no exclusion is stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds some value by making the consequence explicit (permanent removal plus termination of all future scheduled runs), but it says nothing about required permissions, confirmation flow, or behavior when the taskId does not exist.

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 compact sentence with zero filler, front-loading the destructive nature and the resource in the first few words.

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 delete with annotations covering safety and no output schema, the description conveys enough to call it correctly; only permission/error-context detail is absent, which is minor here.

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

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

Only one parameter, taskId, and schema description coverage is 0% – the schema supplies type/format/pattern but no prose meaning. The description never mentions taskId at all, though its name and UUID constraint make it largely self-evident, so the gap is small rather than severe.

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: "Permanently delete a scheduled Replo task" tells the agent exactly what entity is affected and that it is the Replo task resource (paired with get_task/list_tasks). It does not, however, explicitly differentiate itself from other delete-style siblings such as delete_site_page or sightglass_delete_board.

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

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

There is no when-to-use guidance, no stated prerequisites, and no mention of alternatives (e.g., pausing a task versus deleting it). The agent must infer that this is the correct tool purely from the resource noun.

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 destructive=true, idempotent=false, openWorld=true, but the description goes well beyond them: asynchronous internal-agent execution, polling requirement, shared-component edits affecting other pages, execution within the preview, and the correction workflow. This is meaningful side-effect and lifecycle context an agent needs.

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, then the async/correction/publish mechanics. Dense and largely waste-free, though the sentence about the Replo agent's normal tools and integrations is somewhat procedural filler relative to the actionable guidance.

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 async mutation with no output schema, it covers prerequisites, lifecycle (poll get_agent_session), side effects (shared components), and the follow-up publish step. The only minor gap is not describing what the initial invocation returns, though the polling pointer largely compensates.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: sessionId is omitted to start and supplied with an unchanged target to continue, and mismatches are rejected. That workflow meaning for sessionId exceeds a bare field 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 (Edit) and resource (the selected site's draft page at one route), then enumerates the editable surface: copy, sections, product display, forms, page-local components. This clearly distinguishes it from siblings like create_site_page, delete_site_page, update_site, and update_site_metadata.

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 the alternatives and the conditions selecting them: poll get_agent_session for progress, use publish_site separately to go public, and re-call this tool with sessionId for corrections. It also states the precondition (requires a provisioned site), leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the only behavioral nuance not in annotations - that results can come from semantic ranking or metadata filtering - but omits ranked-vs-paginated result behavior and the one-page nature of semantic search, which is instead buried in the cursor parameter description.

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

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

A single front-loaded sentence with the verb and resource first and the mechanism second; no filler or redundancy.

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 no return-shape description, and with 8 parameters at 38% schema coverage plus pagination limits (limit/cursor) unaddressed, the definition is thinner than the tool's complexity warrants. It is minimally viable rather than complete.

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

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

Schema description coverage is only 38% across 8 parameters, so the description must compensate. It usefully groups the inputs into two conceptual modes (searchTerm vs tags/type/label/status), but provides no per-parameter meaning, defaults, or limit/pagination semantics, leaving the burden largely on the schema.

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

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

States a specific verb (find) and resource (media and files in a project's asset library), and distinguishes the library-scoped retrieval from a generic file listing. However it never names a sibling such as list_files or get_file, so the 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?

The phrase 'using semantic search or library metadata' implies two invocation modes, which hints at when each filter set applies, but there is no explicit when-to-use/when-not-to-use guidance and no mention of list_files or get_file as alternatives for the non-search 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description earns credit by adding return-scope behavior ('order summaries only: no customer contact details or payment identifiers') and the money-units convention, which go beyond 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 front-loaded sentences with no wasted framing: purpose first, return scope second, filter recipe third. The currency-format detail is slightly verbose but genuinely useful and does not obscure the core purpose.

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

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

With no output schema, the description carries the return-value burden and does so by describing summaries and the money format. It omits pagination guidance for cursor/limit, a minor gap given the otherwise complete coverage of purpose, scope, and filtering.

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 20% (only financialStatus, with an uninformative 'OrderFinancialStatus' label), so the description must compensate. It clarifies customerEmail usage and the monetary convention, but leaves projectId, limit, cursor, and the financialStatus enum values unexplained. 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 and resource ('Find storefront orders') and scopes the intent ('when investigating a payment state or fulfillment state'). The plural resource implies a list operation, distinguishing it from the singular sibling get_order, though it never names that alternative 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?

Provides a concrete when-to-use trigger (investigating payment/fulfillment state) and a specific recipe for the common lookup case ('to look up a known customer's orders, pass their address as customerEmail'). It stops short of naming when NOT to use it or pointing to get_order for single-order retrieval.

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 useful non-annotation context about result scope (Replo-managed only) and empty-result behavior, but says nothing about pagination despite cursor/limit parameters, which is the main behavioral gap.

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

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

Three short sentences, front-loaded with the core purpose, and the scope caveat and fallback are placed after it. The clause "for catalog, product-page, or checkout work" is somewhat generic, but overall there is little 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?

For a paginated read-only search with no output schema and four undocumented parameters, the description covers purpose and result scope but omits pagination semantics and any return-shape hints. An agent could invoke it, but might misuse limit/cursor or mis-handle the result set.

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

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

Schema description coverage is 0% and the description never mentions any of the four parameters. It does not explain that projectId is required, nor what query matches against, nor how limit/cursor paginate, so it 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+resource ("Find Replo-managed products") and scopes it to catalog/product-page/checkout work. It also draws a clear boundary against products managed by Shopify or other integrations, which helps separate it from the get_product/create_product/update_product siblings, though it never names those siblings directly.

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 usage context (catalog, product-page, checkout work) and an explicit fallback instruction when no Replo-managed products are found. It stops short of naming when to prefer get_product (single-item lookup) or create_product over this search, so alternatives are 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 readOnly/idempotent/non-destructive, and the description adds real protocol context: the tool may yield pending interactions that require user input and a handoff to another tool. It stops short of describing polling cadence, whether status is eventually consistent, or how long a session may run, which would be the remaining behavioral gaps.

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: what is returned comes first, then when to use it, then the handoff rule. The final sentence is long and packs sibling-tool argument formats into the definition, which is useful but strains conciseness for this tool's own scope.

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

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

With no output schema, the description compensates by enumerating the returned fields, and for a one-parameter idempotent read tool it leaves nothing an agent needs before calling. The interaction-resolution path is also fully specified.

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 nothing in the schema describes sessionId semantically beyond its uuid format and pattern. The description never explains where a sessionId comes from or that it identifies the session started by the other agent tools, though the value's meaning is fairly self-evident. The detail about choice vs form answer shapes applies to the sibling tool, not this 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 (retrieve) and resource (Replo session) and enumerates exactly what comes back: status, latest response, tool activity, errors, pending interactions. The pending-interaction content also implicitly separates it from abort_agent_session and resolve_agent_interaction.

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 when to call it ('check progress after starting or continuing a session') and defines the follow-up branch: when pendingInteractions is non-empty, surface it to the user, wait, then hand off to resolve_agent_interaction with the decision/answers shape. Names the alternative tool and the condition that selects 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 cover readOnly, idempotent, and non-destructive. The description adds value beyond them by disclosing an edge-case return ('Returns null when no brand exists') and clarifying that it does not start an agent session, which meaningfully distinguishes it from session-oriented siblings.

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 with no waste: the read scope is front-loaded, the null edge case follows, and the side-effect disclaimer closes. 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 single-parameter read tool with no output schema and full annotation coverage, the description supplies the scope of returned data, the null case, and the no-side-effect guarantee. Nothing needed 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 description coverage is 100% and the single projectId parameter is fully documented in the schema, so the description is not required to carry parameter meaning. It adds nothing beyond the schema, matching the baseline of 3.

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 ('Read') and resource (the project's saved brand kit), and enumerates the contents returned (business info, overviews, colors, fonts, logo marks, personas). It does not name the closely related mutating sibling create_or_update_brand_kit, though 'Makes no changes' implicitly contrasts with it.

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 read framing and the 'Returns null when no brand exists' edge case, which helps the agent interpret an empty result. However, there is no explicit when-to-use vs. when-to-use-alternative guidance against create_or_update_brand_kit or other brand-related siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that it reports activation state and required DNS records, which is useful return-behavior context, but it omits any auth, rate-limit, or failure-mode details.

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

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

A single front-loaded sentence that states the action, the object, and the diagnostic output with zero 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 simple, single-parameter read-only diagnostic tool whose annotations already cover the safety profile, the description is largely sufficient and even summarizes the return content in lieu of an output schema. It falls short only on explaining the identifier it expects.

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 is the only place parameter meaning could be conveyed, yet it never mentions customDomainId or how to obtain it. The name and uuid format make the parameter inferable, but the description does not compensate 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 ('Diagnose') and resource ('connected custom domain') and even names what it inspects ('activation state and required DNS records'). This distinguishes it from siblings like connect_custom_domain and verify_custom_domain, so an agent can tell what the tool is for without opening the schema.

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

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

The phrase 'a connected custom domain' implies the tool applies after a domain is connected, giving implied usage context. However, it never states when to use this versus verify_custom_domain or get_integration_status, and offers no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description's one extra contribution is scoping the return to metadata rather than document content, but it says nothing about behavior on a missing id or any permission requirements.

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

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

A single tight sentence with the action verb first and the key parameter named at the end. No filler, though it is brief enough that one more clause of routing guidance would have fit without bloat.

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 read with no output schema, an agent still lacks the shape of the returned metadata and the error semantics for an unknown id. Safety behavior is fully delegated to annotations, so the remaining gaps are modest but real.

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 has to carry the load; it explains that fileId identifies 'an existing Files document or folder', which is genuinely useful since the schema's uuid pattern does not reveal that both files and folders are addressable. It still does not say where such an id comes from or what the format looks like in prose.

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 ('metadata for an existing Files document or folder'), and the word 'metadata' implicitly separates it from read_file (content) and list_files (enumeration). It does not however explicitly name those siblings, so the differentiation is inferred rather than stated.

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

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

The phrase 'by fileId' implies the precondition that the caller already holds an id, and 'existing' hints that this is a lookup rather than a create. There is no explicit when-to-use versus read_file or list_files guidance and no stated failure behavior for a stale or unknown id.

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 the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description adds meaningful context beyond them: the three possible status values, a dashboard setup URL, and the connectFailureMessage / isAlwaysAvailable / isSettingsManaged fields. It does not cover auth requirements or whether the check is cached, which keeps it out of 5 territory.

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, followed by return values, error semantics, flag meanings, and the exclusion — five compact sentences with no filler or repetition. Every sentence carries distinct 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?

There is no output schema, so the description correctly carries the return contract itself: the status enum, the setup URL, connectFailureMessage, and the two boolean flags. Combined with annotations covering safety and the schema covering inputs, an agent has everything needed to call and interpret this 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 100%, with both projectId and integrationKey documented in the schema itself (including an example value 'figma'). The description adds no format, default, or lookup guidance for the parameters, so the baseline 3 for schema-driven params 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 ('Check one integration's connection status in the selected Replo project') and scopes it to a single integration within a project. It also distinguishes itself from the account-mutation siblings with 'This tool does not connect an account or change permissions,' so an agent can separate it from connect_replo_account without opening either schema.

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

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

The closing sentence gives a clear when-not ('does not connect an account or change permissions'), which is a useful exclusion in a toolset full of connect_* and update_* siblings. However, it never names the alternative tool an agent should call to actually connect or re-authorize, so the routing is implied rather than explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond by disclosing that contact addresses are masked, that no payment identifiers are returned, and that amounts are integer minor units paired with currencyCode. These are exactly the operational details an agent cannot get from 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 sentences, each earning its place: purpose/contents first, privacy handling second, unit conventions third. Front-loaded with no filler.

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

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

With no output schema, the description compensates well by describing the returned contents and value conventions. It omits only edge behavior such as what happens when the order is not found or required access scope, which is minor for a read-only getter.

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, self-evidently named parameter (orderId) and the schema supplies format=uuid and a strict pattern, so the type is documented structurally. However, schema description coverage is 0% and the description adds no meaning about the identifier, so the schema effectively carries the parameter on its own.

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 (one storefront order) and enumerates the contents returned (line items, fulfillment, refunds, event history). The word 'one' implicitly distinguishes it from find_orders, so an agent can tell search from single-fetch without opening the schema.

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

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

Usage is implied by 'one storefront order' versus the plural find_orders sibling, but the description never states when to use this versus search, nor any prerequisistes such as needing a known orderId. The context is inferable but not 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description usefully discloses the data content (current plan, prices, Sightglass feature deltas), but adds nothing about auth requirements, plan-gating limits, or freshness — a moderate contribution given annotations do the heavy lifting.

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

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

Two sentences, front-loaded with what is returned and then when to invoke it. Every clause carries information — plans covered, prices, feature deltas, and trigger conditions — 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 read-only, single-parameter tool with no output schema, the description adequately previews the return content (current plan, monthly prices, Sightglass additions) and the situations that should trigger a call. 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% and the single workspaceId parameter is fully documented in the schema with its UUID format and source (list_workspaces). The description only alludes to workspace scoping ('The workspace's current plan') without adding format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — retrieves the workspace's current Replo plan plus the Starter and Pro plans' prices and the Sightglass features they unlock. This is clearly distinct from the sibling start_plan_upgrade, which performs the action rather than reporting options.

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

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

Gives explicit trigger conditions: when a result names a locked field or a higher plan, or when the user asks about upgrading. It does not explicitly name start_plan_upgrade as the tool to call once the user decides to act, so the alternative is 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 readOnly, idempotent, non-destructive, and closed-world, so safety is fully covered. The description adds only mild context via 'current public catalog details,' implying a fresh read of published/customer-facing fields rather than admin-internal fields, but it does not disclose return shape, caching, or error 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, stating the action, the resource, and the scope of the data returned. Nothing restates the tool name needlessly.

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

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

The tool is a simple, fully annotated read with one UUID parameter and no output schema, so safety and typing are covered elsewhere. The only meaningful gap is that the description does not tell the agent how to obtain a valid productId, which matters given 0% schema coverage.

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

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

With a single required parameter and 0% schema description coverage, the schema supplies type/format/pattern but no prose meaning. The description's phrase 'a specific Replo-managed product' scopes the ID to Replo-managed products, which is modest added value, but it never says where the productId comes from (e.g., find_products).

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 resource (public catalog details for a Replo-managed product) clearly states what the tool returns. It is distinguishable from find_products (search) and update_product (mutation), 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?

Usage is implied: fetch one product when you already have its identifier. There is no explicit when-to-use guidance, no statement about when to prefer find_products for discovery, and no note on prerequisites such as owning or having access to the product.

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 it a safe, idempotent read, so the bar is lower; the description nevertheless adds a non-obvious behavioral fact ('connecting Shopify does not switch checkoutProvider') and the null-means-checkout-is-off semantics. It stops short of noting caching or data freshness, which keeps it from a 5.

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

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

Two dense sentences, front-loaded with the returned fields and followed by the usage warning; the parenthetical enum decoding earns its space. Slightly heavy on clauses but no filler.

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

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

There is no output schema, so the description appropriately lists the return fields and decodes checkoutProvider. For a single-parameter read tool this is nearly complete, though it could clarify what happens for an unknown or malformed projectId.

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 description never mentions projectId its expectations at all. The parameter name is self-explanatory and its UUID format is enforced by the schema, so the omission is tolerable, but the description does not compensate 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 (read) and resource (one Replo project's settings), then enumerates the exact fields returned (name, time zone, currency, support email, checkoutProvider). This clearly distinguishes it from sibling getters like get_product, get_order, or get_brand_kit.

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 when-to-use trigger: check checkoutProvider before promising Shopify checkout or when a Shopify-connected site's Checkout button fails. It does not, however, explicitly contrast the tool with list_projects or other siblings, so routing among alternatives is left partly implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description usefully adds that the payload concerns the task's schedule and current timing, but says nothing about return shape, pagination, or errors.

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 efficient sentence with the resource front-loaded and zero filler. It is perhaps too terse given the remaining gaps, but there is no wasted wording.

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

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

For a simple single-parameter read tool whose annotations cover safety and with no output schema required, this is adequate but thin: it does not say how to source the taskId or what fields come back, which matters for a 0%-coverage schema.

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

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

Schema description coverage is 0% and the description never mentions taskId, its UUID format, or where the ID can be obtained (e.g., from list_tasks). With a single low-coverage parameter the description is expected to compensate and does not.

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

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

States a clear verb (inspect) and resource (a specific recurring Replo task), and the word 'specific' implies a single-task lookup. It does not explicitly differentiate itself from the sibling list_tasks, so it falls short of a 5.

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

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

Usage is only implied: the agent should call this when it already has one task in mind, versus list_tasks for enumerating tasks. No explicit when-to-use, prerequisites, or named alternative is 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world, so the safety profile is covered. The description adds useful scope context (My Files default, assets excluded) but says nothing about pagination behavior or result shape for a list that clearly supports cursor/limit.

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

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

Two short sentences, no waste, with the core scoping fact and the My Files rule front-loaded. 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 read-only list tool with annotations covering safety and no output schema, the description supplies purpose, default scope, and a sibling boundary. The one notable omission is any hint about pagination despite cursor/limit parameters.

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

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

Schema description coverage is 0%, so the description must carry the load: it meaningfully explains parentId (omit for My Files) and implicitly maps to the kind enum via "documents and folders." However, cursor and limit are left entirely undocumented, 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 ("List private working documents and folders") plus the scoping container ("in a project"). It also distinguishes itself from the asset siblings by noting that assets are a separate media library, so an agent can route list_files vs find_assets without opening schemas.

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

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

"Omit parentId for My Files" gives concrete when-to-use guidance for the root listing case, and the asset sentence sets a boundary against find_assets/upload_asset. It stops short of explicitly contrasting with get_file/read_file, so it is clear context without full alternatives coverage.

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), but the description adds real behavior beyond them: pagination via next_cursor and an alternative return shape ('setup_required with eligible workspaces'). It doesn't discuss rate limits or result ordering, 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 the purpose and kept to four short sentences, each carrying useful information (scope, when-to-use, return shape, pagination). Slightly more prose than strictly needed, but nothing is redundant filler.

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

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

With no output schema, the description correctly takes on the burden of describing returns ('paginated projects or setup_required with eligible workspaces') and tells the agent how to page. The remaining gap is the undocumented 'limit' parameter.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It covers workspaceId ('within one workspace') and cursor ('Follow next_cursor when more results are needed'), but the 'limit' parameter is undocumented in both schema and description and no format guidance is given, so it only partially compensates.

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

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

States a specific verb and resource ('List accessible Replo projects') plus scope ('optionally within one workspace'). The line 'Listing does not create a project' actively distinguishes it from the sibling create_project, so the agent doesn't confuse the two 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?

'Use to resolve the project for the user's Replo request' gives a clear context for invocation, and 'Listing does not create a project' implicitly signals when not to use it. However, no alternative sibling (e.g. get_project when the ID is already known) is named, so it stops short of explicit routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds meaningful behavior beyond that: the returned fields (clone_url, is_default), the pagination contract (follow next_cursor until has_more is false), and the caveat that site names are dashboard labels, not SEO titles.

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

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

The purpose is front-loaded and each sentence carries operational value (default-site logic, pagination, name semantics). It is dense at five sentences but nothing is filler or 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?

For a read-only, single-project list tool with no output schema, the description covers purpose, return fields, default-selection logic, pagination, and a naming caveat. The only gap is the unmentioned limit parameter and its bounds.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It implies projectId ('within a project') and cursor (via the next_cursor pagination note), but never explains limit, and the cursor mention refers to the response field rather than the input 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?

The description states a specific verb and resource ('Find the Replo site ... within a project') and frames the tool's intent as inspect/manage/clone, which distinguishes it from sibling list tools like list_projects or list_workspaces. An agent can tell what it does 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 decision logic: use the site with is_default=true when the user doesn't name one, and ask for clarification if none is default. It also instructs to page through next_cursor before concluding a site does not exist, covering the when-to-use and when-not-to-conclude cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it never mentions that results are paginated, how limit/cursor interact, or what ordering to expect. With annotations carrying the safety story, a minimally additive description lands here.

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 zero filler. It is efficient, though the brevity tips into under-specification rather than disciplined conciseness.

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

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

For a paginated list tool with no output schema and three undocumented parameters, the description is too thin. An agent cannot tell whether listing requires additional scoping, how to page, or whether results are bounded.

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 three parameters. The phrase 'in a project' faintly implies projectId is the scoping key, but limit and cursor are entirely unexplained, and pagination semantics are the one thing the schema cannot convey on its own.

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+resource+scope: list scheduled tasks within a project. It is legible on its own, but it does nothing to distinguish itself from siblings such as get_task or delete_task, and 'scheduled' is the only qualifier that separates it from a generic task listing.

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 when-to-use guidance, no prerequisites, no mention of alternatives like get_task for a single task. The agent must infer from the name alone that this is the enumeration path for tasks.

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, so safety is covered. The description adds genuine context beyond them: it reveals the tool's role in the auth/workflow chain and that the returned id feeds workspaceId on Sightglass calls, plus the plan values it returns. It stops short of describing response shape/pagination, but no output schema means that gap is minor.

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

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

Front-loaded with the resource and its return content, with usage details following. Every clause carries workflow value; it is slightly dense but nothing is wasted or padded.

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

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

For a read-only, zero-parameter list tool with no output schema, the description supplies what's needed: what is returned (workspaces + plan tiers), when to call it, and how the result is consumed downstream. 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4. The mention of the workspaceId it produces is useful downstream context, not a parameter gloss.

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 ('the user's Replo workspaces') and adds what each entry carries ('each one's plan (free, starter or pro)'). An agent can distinguish this from the sibling list_* tools immediately.

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

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

Explicitly prescribes when to call: right after sign-in, and when the user wants to switch workspaces. It also gives the decision procedure (use the only workspace, or ask once when several exist) and how to use the result (pass id as workspaceId on Sightglass calls).

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, so the safety profile is covered. The description adds real value by disclosing the internal pipeline (builds, packages, uploads, deploys), signaling a heavy multi-stage operation. It still omits whether the deploy is asynchronous, how failures surface, or what state is left behind on a partial failure.

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, effect stated first, prerequisite second, mechanism last. No filler and nothing buried.

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

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

With no output schema, the description still tells the agent the required input source and the overall effect. It is nearly complete for a publish operation, lacking only failure/timeout behavior, which matters given the multi-stage build-and-deploy it describes.

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

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

Schema description coverage is 100%, so both parameters are already documented in detail — including promoteRoutes' publish/draft semantics. The description's 'Requires the siteId from list_sites' merely repeats the schema's own note and says nothing about promoteRoutes. Baseline 3 applies.

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

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

States a specific verb and resource (publish a site) and clarifies the effect — 'make changes live' — which separates it from draft-editing siblings like update_site and from create_shared_preview. It does not explicitly name an alternative 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?

It gives a prerequisite ('Requires the siteId from list_sites'), which is genuinely useful routing, but never states when to prefer this over alternatives such as update_site (draft edits) or create_shared_preview (non-live preview). Usage is implied by 'make changes live' rather than argued.

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, but the description adds genuinely non-obvious behavior: only SELECT/WITH are accepted, project-scoped tables are server-side filtered to the requested project plus authorized same-workspace/same-store siblings, and limits/examples live in external docs. Execution-time and row caps are only in the schema, not the description.

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 sentences, front-loaded: purpose, table inventory, write-restriction, scoping rule, doc pointer. The table enumeration partially duplicates the schema, but at four sentences total nothing is bloated.

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 with no output schema and a highly complex query surface, the description covers the accepted syntax, the scoping model, the table inventory, and offloads column/limit detail to referenced docs. Missing only the shape of the returned result set, which an agent might reasonably want before parsing output.

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% (the uuid projectId has no description), so the description carries weight by explaining that project scoping is enforced server-side against projectId rather than left to the caller's WHERE clause. The `query` param is exhaustively documented in the schema itself, so the description rightly doesn't repeat it.

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

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

Opens with a specific verb and resource: 'Run read-only ClickHouse SQL over a project's Replo analytics for traffic, conversion, revenue, and session-level questions.' No sibling tool does anything comparable, and the read-only/SQL framing immediately separates it from the REST-style find_/get_ 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 real routing guidance among the queryable tables: it names the six tables and, in the schema, distinguishes session_attribution (cross-project revenue) from project-local rollups with deduplication advice. It stops short of explicit when-not-to-use-this-tool or a named alternative for non-SQL analytics needs.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description goes beyond them by disclosing the conditional return behavior (inline content vs temporary download URL), which is the key non-obvious trait for this tool. It omits the size threshold that triggers the switch and the URL's expiry window.

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 primary mode (inline read) precedes the fallback (download URL), which is the correct emphasis.

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 what comes back (document content or a download URL) and why the branch occurs, covering the main return-value ambiguity. It is slightly thin on error/edge behavior for a nonexistent file, but adequate for a single-param read tool whose safety annotations are complete.

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

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

The schema has 1 parameter with 0% description coverage, and the description never mentions fileId, its UUID format, or where it can be sourced. Since the schema does not compensate, the description should have carried the burden and does not.

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

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

The description names a specific verb (Read) and resource (Files) and, unusually, splits the behavior into two concrete outcomes: inline UTF-8 content for small documents versus a temporary download URL for binary/larger files. That is clear purpose. It stops short of distinguishing itself from the sibling get_file, so an agent still cannot tell the two apart from the text 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?

Usage is only implicit: small UTF-8 documents yield content, binary/larger files yield a URL. It never states when to choose this over the near-identical get_file sibling, nor any prerequisite such as needing a fileId from list_files or find_assets.

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

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

Annotations cover only the generic safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description goes well beyond that: it discloses the destination of the side effect ('Files feedback with Replo's team'), the non-idempotent follow-up rule, privacy constraints ('Omit credentials and unrelated customer data'), and an evidence-integrity requirement ('never invent evidence, root cause, or severity'). That is materially more than the structured fields 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?

The paragraph is front-loaded with purpose and stays dense with rules, so every sentence carries operational weight. There is some redundancy with the schema ('Mark unknowns; never invent evidence' is restated in the reproSteps and description field docs), which slightly inflates length but does not obscure the intent.

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 say what a successful call yields; it instead only says feedback is filed and the agent should continue, leaving the return value (e.g., a report or ticket ID) unstated. Given the annotations and 80% schema coverage, the rest of what an agent needs to call this correctly is present.

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

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

Schema coverage is 80%, so most parameters are self-documenting and a baseline of 3 would apply. The description compensates for the one uncovered field by specifying exactly what belongs in errorContext ('observed errors or request IDs'), and it reinforces projectId sourcing from list_projects. It adds real meaning rather than restating schema text.

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

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

The description names a specific action and target ('Report a credible user-reported or directly observed Replo defect, including API, MCP, or documentation defects'), which is far more precise than the title 'Report a bug'. It does not distinguish itself from the closest sibling, submit_feature_request, so an agent still has to infer which filing channel applies. Clear purpose, missing sibling routing.

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 inclusion criteria (credible, user-reported or directly observed Replo defects) and exclusion criteria (bad arguments, missing configuration, fixable site-code mistakes), plus a post-success rule ('Do not resubmit the same report after success'). No alternative tool is named, so the when-to-use is strong but the alternatives branch is absent.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description meaningfully expands on that: approving/answering resumes the agent which 'can then overwrite or delete content, publish, or write to an external service.' It also discloses the failure mode (non-pending interaction errors, nothing delivered) and the return value (updated session status).

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

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

Front-loads the action, then the type-specific parameter contract, then the risk, then the error recovery. Five dense sentences with no filler or repetition of the enum values already 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?

For a 5-parameter destructive, open-world mutation with no output schema, the description covers the required inputs, the type-dependent payload shape, downstream side effects, and the error/retry behavior. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 80%, and the description still adds real meaning beyond it: the answers array is one array per form step in order, may hold custom text only where that step's allowCustom is true, and an empty array skips a step. It ties 'decision' to the interaction's response options, which the schema only loosely references.

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 immediately scopes it to the user's explicit answer. It is clearly distinguishable from siblings like get_agent_session (read) and abort_agent_session (terminate) because it is the delivery of a user decision.

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 branching guidance: 'For a permission request, pass type permission and the decision...' vs 'For a question, pass type question and one answers array per form step.' It also gives a constraint ('Never infer an answer') and a recovery path ('call get_agent_session again') for stale interactions.

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 clarifies that repeated requests succeed (reinforcing idempotentHint with concrete semantics), that page content is preserved despite destructiveHint=true, and that revocation is permission-gated. This is exactly the kind of auth/reversibility context an agent needs before invoking a destructive mutation.

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, each carrying distinct information: purpose, authorization, idempotency/content preservation, and a scope guardrail. Purpose is front-loaded and nothing is redundant.

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

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

No output schema exists, and the description covers the remaining gaps for a single-parameter destructive mutation: who may call it, repeat behavior, and that page content survives. Nothing needed to call it correctly is missing.

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

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

The schema has 0% description coverage for sharedPreviewId, so the description must compensate; it does by stating the id comes from create_shared_preview, giving the parameter provenance and meaning the bare UUID pattern/format does not.

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

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

States a specific verb (Disable) on a specific resource (public shared preview link) and names the sibling that creates it (create_shared_preview). An agent can distinguish this from create_shared_preview or delete_site_page 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 states the authorization condition for use (creator with current project access or workspace admin) and adds an operating constraint ('Revoke only the link the user requested'). It gives clear context but does not name an alternative tool or state when not to use 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds value beyond them by clarifying that 'available' is an absolute count rather than a delta and by documenting the refusal behavior for POD/digital variants, though it doesn't spell out what happens to variants omitted from the update.

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 sentences, front-loaded with the core action, and each subsequent sentence adds a distinct operational constraint rather than padding. Slightly dense run-on phrasing in the opening sentence, but nothing is wasted.

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

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

For a mutation tool with annotations present and no output schema, the description covers the key behavioral traps an agent would hit. It could be more complete about batch semantics (whether omitted variants are untouched and how maxItems=250 affects large products), but nothing critical for a correct call 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?

With 0% schema description coverage, the description must carry the parameter burden. It explains the semantics of 'available' (absolute, not delta), 'optionValues' (empty for optionless products), and 'trackInventory' (must be paired with a count), but 'continueSellingWhenOutOfStock' and 'productId' are never addressed.

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

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

The description names a specific verb and resource ('Set stock counts and stock policy for a Replo-managed product's variants') and scopes it to variant-level inventory rather than general product editing, so it reads distinctly from update_product. It stops short of naming a sibling explicitly as the alternative, so it is clear but not fully differentiated.

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 real operating conditions: turning on trackInventory without an available count leaves the variant unsellable, so both should be set together, and only merchant-fulfilled products can track stock while print-on-demand and digital variants are refused. That is strong when/when-not context, but no sibling alternative (e.g. update_product) is named for the non-inventory case.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: results are data only and nothing renders until sightglass_show, locked plan-gated fields return null and are named in `locked`, `lockedCount` signals what a higher plan reveals, and the agent is told never to estimate locked data. This is exactly the extra context annotations cannot carry.

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 scope are front-loaded, and despite its length most sentences carry distinct load-bearing information (axes semantics, plan locking, show routing). A few clauses restate schema content (kind values) and the map framing is mildly redundant, so it is dense but slightly over-full.

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 with no output schema, the description fully characterizes the return shape: a 0-100 position per axis, raw similarity, locked/lockedCount, and isYou marking, plus the two-step show workflow. Nothing material to calling 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 the baseline is 3, but the description adds meaning: a worked custom-axis example ([{low:'Minimal', high:'Maximal'}]), the rule that omitting `high` auto-names the opposite, and that the user's own company/Brand Studio personas are always included and marked isYou. The explicit lens preset pairs also reinforce the enum beyond the schema's terse mapping.

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

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

States a specific verb and resource: placing personas, ads, landing pages or companies onto 'this vs that' axes on the Sightglass Arena map. It situates itself clearly against siblings by naming the map UI and the sightglass_show follow-up, so an agent can tell what it does without opening the schema.

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

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

Gives concrete triggering questions ('where do we sit against these brands', 'which buyers are nobody's focus') and explicit lens-vs-custom-axes guidance, plus the crucial routing rule to call sightglass_show with resultId afterward. It lacks an explicit 'when not to use' or contrast against search/research siblings like sightglass_xray or sightglass_get_rankings.

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, but the description adds real behavioral context: the cross-system copy from Sightglass into Replo, and the concrete idempotency outcome ('copying the same creative again returns the existing asset'). It also discloses auth-relevant scoping indirectly via project/workspace. Return payload is noted, though side effects on the plan/charge are left to 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?

Three short sentences, well front-loaded: purpose first, the key parameter caveat second, the return/idempotency behavior last. Every sentence carries information an agent needs.

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 explains the return value (asset id and URL) and the idempotent repeat behavior, plus the source/destination systems. For a 3-parameter, fully-documented tool with annotations covering the safety profile, nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the creative.id-not-ad-id note. The description reinforces that same gotcha but adds no new parameter meaning (no format, defaults, or workspace requirement) beyond the structured fields.

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 (copy one ad creative's image) plus the source and destination systems (Sightglass → Replo project Assets). An agent can distinguish it from sightglass_get_ad, upload_asset and other asset/file tools without opening any schema.

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

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

Explains the intent ('so it can be used as a reference in the project') and gives the critical usage caveat to pass the creative.id rather than the ad's own id. It does not name an explicit alternative tool or when-not-to-use, but the context for calling it 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 declare the safety profile (mutation, not idempotent, not destructive, closed-world), so the bar is lower. The description usefully adds that the created board and its id are returned, which matters because there is no output schema, but it does not disclose whether duplicate names are allowed, what happens on repeat calls (non-idempotent), or any plan/permission requirements beyond what the schema states.

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 what is created, followed by the domain constraint and the return value. Every sentence carries distinct 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 four-parameter, output-schema-less mutation tool the description does the important work of naming the return value and the kind constraint. It stops short of covering edge behavior (name uniqueness, error cases, where the new board surfaces in the collection), but nothing essential to making the call 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 75%: projectId and workspaceId are documented in the schema (including the multi-workspace requirement), and kind carries its own enum description. The description largely restates the kind enum rather than adding meaning, and says nothing about the undocumented name parameter beyond its requiredness.

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') and goes further by defining the domain object: a board holds exactly one kind of item (ad, site_page, company, persona). Combined with the close siblings sightglass_update_board and sightglass_delete_board, an agent can identify this as the creation operation without opening the schema.

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

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

Usage is implied by the creation semantics but never stated explicitly: there is no guidance on when to create a board versus using the sightglass_list_saved/find_* flows, no prerequisites, and no note about coexisting boards. The one-kind-of-item rule is a constraint on the tool rather than a routing instruction.

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 structurally. The description earns credit for going beyond that by naming what is destroyed ('everything saved on it') and stating irreversibility ('This cannot be undone') — details the annotations do not express. It stops short of mentioning permission requirements or downstream effects on other objects.

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

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

Two tight sentences: the destructive scope leads, the irreversibility and usage gate follow. No filler, nothing buried.

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

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

For a destructive, no-output-schema tool with strong annotations, the description covers what gets destroyed and that it is irreversible — the essentials for safe invocation. Minor gaps remain around permissions and any side effects on objects referencing the deleted board.

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%: boardId is undocumented but typed as a UUID, while projectId and workspaceId carry their own descriptions. The tool description adds nothing about any parameter, so it neither compensates for the boardId gap nor clarifies when workspaceId is required. Baseline 3 is appropriate when the schema does most of 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 (Delete) and resource (one of the user's Sightglass boards) and clarifies scope by noting everything saved on the board goes with it. An agent can distinguish it from sightglass_create_board and sightglass_update_board 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 an explicit gating condition: 'only call it when the user asked for this board to be deleted.' That is a real when-to-use constraint, though it doesn't name the sibling (update_board) that covers non-destructive modification of the same resource.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: performanceScore/scoreTiers are a longevity+duplication heuristic, NOT spend/reach/ROAS; plan-gated fields return null and are listed in `locked`; lockedCount signals more results on a higher plan; the tool returns data only and nothing is shown until sightglass_show is called.

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 and most sentences carry unique operational information, but it is a dense single block with mild redundancy (the 'not spend, reach or ROAS' caveat appears twice, and the plan-locked explanation is split across two clauses). Slightly tighter grouping would help an agent parse it.

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 16 optional params, no output schema, and no required fields, the description covers what is needed: what comes back (metadata + media URLs), pagination via cursor, the resultId → sightglass_show handoff, and the plan-gating behavior. An agent can call it correctly without further context.

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

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

Schema coverage is already 88%, so the schema carries most of the parameter semantics. The description still adds real value by explaining the semantics of `search` (vector search over copy, caption, advertiser), translating user vocabulary onto companyIds/pageTypes, and warning that scoreTiers/performanceScore are heuristic, not ad spend.

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

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

Opens with a specific verb+resource: searching a library of real Meta ads and the landing pages they drive to. It further distinguishes itself from siblings by naming sightglass_get_ad and sightglass_get_site_page as the single-item lookups, and from sightglass_find_site_pages as the ad-side search.

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 guidance on how to phrase `search` (semantic, describe angle/offer/visual style, not one keyword), which filter groups do what (narrow vs. creative-read tags), vocabulary mapping ('brands' → companyIds, 'landing pages' → pageTypes), and the follow-up workflow: call sightglass_show with resultId once you know the answer, and it can be called before sign-in.

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

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

Annotations cover the safety profile, and the description adds substantial behavior beyond them: plan-gated fields return null and are named in each item's `locked` list, `estimates` maps to sales/visits/traffic, `lockedCount` indicates how many more results a higher plan yields, the agent must say data is on a higher plan and never estimate it, and the tool returns data only with nothing shown until sightglass_show is called.

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 long but front-loads the core concept and every clause carries information (field inventory, sort order, plan-locking, show workflow). The single dense paragraph is heavy to parse, 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?

There is no output schema, so the description carries the return-value burden and does so by enumerating angle fields, counts, dates, offers, and the locked/estimates mechanism. It also covers the required handoff to sightglass_show, leaving nothing essential unspecified.

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

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

Schema description coverage is 100%, so companyRef, projectId and workspaceId are already fully documented in the schema. The description adds no parameter-level syntax or format detail 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 gives a concrete verb+resource and defines what an 'angle' is in domain terms (the pitch each ad leans on, with type, name, hook, persona, offers), which clearly separates it from offers or personas. It stops short of naming its nearest sibling (sightglass_find_top_angles) to draw the boundary explicitly.

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

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

It states the intended questions ('how does this brand sell', comparing two brands' messaging) and gives an explicit follow-up rule: call sightglass_show once with this call's resultId, which does not re-search. No when-not-to-use or alternative-tool guidance, so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: results are data-only and nothing is shown to the user until sightglass_show is called, plan-gated fields return null and are enumerated in each item's `locked` list, `lockedCount` signals truncated results, and the agent must tell the user the data is on a higher plan rather than estimating it. These are exactly the operational caveats 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?

It is front-loaded with the payload description, then the result shape, then the show-it workflow, and every sentence carries information. It is dense and slightly long, but no sentence is filler.

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

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

With no output schema, the description carries the full burden of describing returns: field contents, null/locked behavior, lockedCount, and the required sightglass_show step. An agent has everything needed to call it, interpret the result, and render 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 description coverage is 100%, so the defaults for from/to, the companyRef 'id or slug' note, and the workspace/project scoping are already documented in the schema. The description adds result semantics (discount steps) rather than parameter meaning, 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 gives a specific verb and resource ('A brand's offer campaigns'), enumerates what each campaign contains (deal type, date range, depth, ad/page counts, exact quote), and explains the grouping/steps logic. It is very clear what the tool returns, though it never distinguishes itself from the overlapping sibling sightglass_find_offers, which an agent must resolve on its own.

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 concrete usage contexts ('answer what is this brand running', 'compare two brands' promotions') and gives an explicit follow-up workflow (call sightglass_show once with the resultId to render cards, noting show does not re-search). It stops short of saying when to prefer this over find_offers, but the when-to-use guidance is otherwise 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 read-only/idempotent/non-destructive safety profile, and the description adds substantial behavior beyond that: plan-gated fields return null and are named in the item's `locked` list, `lockedCount` counts additional higher-plan results, and the caller must not estimate locked data. It also discloses that the tool returns data only ('nothing is shown to the user yet'), which is critical workflow 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?

Dense but nearly every sentence carries required information (mode logic, sort options, plan-locking, show workflow, resultId). It is front-loaded with the resource and mode split, though the single flat block could be broken into clearer segments.

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 explain results — and it does, covering the locked/lockedCount fields, the null-for-unauthorized-plan behavior, and the resultId handoff to sightglass_show. For an 8-parameter research tool with no required params and zero annotation-sourced return info, this is complete enough to invoke correctly.

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

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

Schema coverage is 88%, so most parameters are documented in the schema; the description adds cross-parameter semantics the schema cannot express — that presence/absence of companyRefs toggles mode between 'top' and 'calendar' — plus the plan-gating/`locked` semantics tied to projectId/workspaceId. This is meaningful added value over the per-field 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?

States a specific resource (offer campaigns across brands) and clearly delineates two distinct behaviors: 'top' mode without companyRefs and 'calendar' mode with companyRefs. An agent can tell this is an offer-discovery tool, distinct from sibling ad/angle/campaign finders.

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?

Names two concrete user intents it serves ('what offers are working in this market', 'when do these brands run sales') and maps each to the mode selected by whether companyRefs is supplied. It also explicitly routes the follow-up step to sightglass_show with resultId, so the agent knows the full call sequence.

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

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

Beyond the read-only/idempotent annotations, it discloses plan gating with locked fields and lockedCount, that missing-plan fields return null, that the user must be told data is on a higher plan, that output is data-only until sightglass_show is called with resultId, and that show does not re-run the search. This is unusually rich 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?

The description is front-loaded with the persona definition and then covers plan gating and the show workflow. It is longer than a minimal definition but most sentences carry practical value; the field inventory is slightly verbose but justified by the absence of an output 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 supplies the return-shape detail (segment nickname, buyer situation, ad share, counts, top angles/offers), the locked-field behavior, and the downstream sightglass_show step. An agent has everything needed to call it and handle the result.

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

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

Schema description coverage is 100%, and the schema already explains companyRef, projectId, and workspaceId. The description adds plan-related context but no parameter-specific syntax or format beyond what is structured, 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 opens with a specific resource — 'A brand's customer personas' — and immediately defines the content: who the brand markets to, age range, awareness stage, angles and offers. This clearly distinguishes it from sibling tools like sightglass_find_angles or sightglass_find_offers.

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

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

It gives concrete use cases ('answer who is this brand selling to' or compare two brands' audiences) and a key prerequisite ('Empty until the brand has enough ads and pages read'). It does not name alternative tools or state when not to use it, so it stops short of explicit routing.

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

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

Annotations already cover read-only/idempotent safety, but the description goes far beyond: it explains plan-based gating ('fields the plan doesn't include come back null and are named in that item's locked list'), defines lockedCount and estimates, instructs 'never estimate it yourself', notes nothing is shown to the user yet, and states it needs no Replo account. This is exactly the extra behavioral context annotations cannot carry.

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 densely front-loaded: purpose first, then filters, then plan gating, then the show workflow and the auth note. Nearly every sentence carries operational weight, though the two-part emphasis on locked fields/plan messaging is slightly repetitive.

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 10-parameter tool with no output schema, the description covers the non-obvious return behavior (locked fields, lockedCount, resultId for sightglass_show) and the auth precondition. It does not describe the general shape of a returned page record or restate pagination, leaving a small 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?

With 70% schema coverage the baseline is a 3, but the description adds real meaning: it enumerates the semantic values and clarifies that `search` is semantic over title and description (not documented in the schema), and gives concrete technology examples (Shopify, Klaviyo). It still leaves `sort` and `activeAdsCountGte` unexplained, so not a 5.

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

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

States a specific verb+resource ('Find destination pages ads drive to') and immediately disambiguates the jargon by equating it to 'landing pages'. It is clearly distinguishable from siblings like sightglass_get_site_page (single page) and sightglass_find_ads/find_technologies (different resources).

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 pipeline guidance: this tool returns data only, then call sightglass_show once with resultId to render cards, and it can be called before the user signs in. It does not, however, contrast itself against the other find_* siblings (e.g. when to use find_technologies over this), which keeps it short of a 5.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: results are data-only with nothing surfaced to the user, the resultId must be handed to sightglass_show (which does not re-search), and the call works unauthenticated before sign-in.

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 definition, then parameter routing, then the show/auth workflow. Every sentence carries information, though the workflow and auth notes make it longer than a minimal definition.

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

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

With no output schema, the description still covers the key return contract (data-only, resultId, show call) and auth requirements. It leaves the projectId/workspaceId plan-applicability behavior implicit for a 7-param, zero-required tool, which is the main 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 coverage is 57%, and the description clarifies the highest-stakes parameter (`slug` switches to a single-technology view) and ties the default directory output to the ranking/sort concept. It does not explain sort's enum options, limit, search, or the projectId/workspaceId plan-selection semantics, so it only partly compensates.

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

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

States a specific resource and scope: 'the apps and vendors detected on tracked brands' sites (Shopify, Klaviyo, Recharge…), ranked by how many brands use each.' Concrete examples plus the ranking basis let an agent distinguish it immediately from sibling finders like find_ads or find_site_pages.

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: pass `slug` for one technology's stats, and pass the technology name as `technologies` to sightglass_find_ads or sightglass_find_site_pages to get the underlying brands/ads. It also states the follow-up show workflow and that no Replo account is needed, so when/when-not is fully covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: plan-gated fields return null and are enumerated in `locked`, `lockedCount` explains truncated results, and it instructs the agent to tell the user the data is on a higher plan rather than estimating. It also discloses that the call returns data only and requires a follow-up sightglass_show with the resultId.

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

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

Front-loads what the tool is and its sibling relationship, then layers filtering, plan-gating, and the show workflow in a single dense paragraph. Every sentence carries information, though the run-on structure of the middle sentences makes it slightly harder to scan than it needs to be.

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 return shape's notable behaviors (null + `locked` for plan-gated fields, `lockedCount`) and the resultId handoff to sightglass_show. It is a tool with 8 params and no required ones, and the gaps are the unmentioned `days`/`limit` semantics and pagination limits.

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

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

Schema coverage is 75% and four parameters are enums, so the schema already carries most semantics. The description adds meaning for `type`, `ageBand`, `awareness` and the sort options, but says nothing about `days`, `limit`, defaults, or why `projectId`/`workspaceId` both exist. This is baseline-level support on top of an already-documented schema, not compensation.

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 (angles) and pins the scope as cross-brand: 'the angles in use across every tracked brand.' It explicitly positions itself against the sibling sightglass_find_angles ('the same shape as sightglass_find_angles, with the brand on each'), so an agent can distinguish the two 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 concrete usage contexts ('what pitches are brands using on this audience', 'find an angle nobody is running') and names the filters and sorts available. It implies but never explicitly states when to reach for sightglass_find_angles instead of this cross-brand variant, so the routing guidance stops short of a full when-not 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 flag destructiveHint=true and idempotentHint=true but do not say what is destroyed; the description supplies exactly that — companyIds replaces the entire list, so omitted brands are dropped, and it tells the agent to re-include keepers. It also discloses downstream effects on the home view and offer calendar, which 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?

Two sentences, zero waste: the first states the action, the second front-loads the destructive replace caveat before the recovery instruction. No restated name or title padding.

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

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

For a 3-parameter mutation with no output schema, the description covers the action, the destructive replace behavior, the recovery workflow, and the downstream effect, while the schema covers the remaining parameter semantics. It could mention the 200-item cap or error case when an invalid company id is passed, but nothing essential is missing.

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

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

Schema description coverage is 100%, so projectId, workspaceId, and companyIds are already documented in-schema, including the replace semantics of companyIds. The description reinforces that replace semantics but adds no syntax or format detail beyond the structured fields, so the baseline 3 applies.

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

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

States a specific verb and resource ("Set the brands the user follows in Sightglass") and immediately clarifies that this is a full replace, not an incremental follow. An agent can distinguish this from read-oriented siblings like sightglass_list_saved or sightglass_get_company 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?

Explicitly names the prerequisite read step and the alternative tool ("read the current one with sightglass_list_saved (kind=following) and include the ones to keep"), giving an actionable read-modify-write workflow. It also states the downstream consequence (home view and offer calendar) that motivates using it at all.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the burden is lower. The description adds genuine behavioral context beyond that: it ties locked fields to plan limits, explaining why this read is the diagnostic for gated content, and frames the plan as the gate for research. It does not add rate-limit or response-format detail, but the annotation coverage makes that acceptable.

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

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

Front-loaded with what the tool returns, followed by a clean usage sentence. The return-field enumeration is somewhat long but every item is informative rather than filler; slight trimming would make it tighter.

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 shoulders the burden by enumerating the returned fields and explaining the diagnostic role of the tool. For a simple read with two schema-documented optional params, this is nearly complete; only return value ordering/shape nuances are left unspecified.

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

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

Schema description coverage is 100%, so projectId and workspaceId are already fully documented in the schema (source, purpose, and when workspaceId is required). The description adds nothing about the parameters, 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 states a specific verb+resource (retrieve the user's Replo/Sightglass plan) and enumerates exactly what it returns: plan name, per-list row caps, estimate inclusion, history/trend windows, and research usage. This is far more than a restatement of the title and lets an agent know precisely what 'access' means here.

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 two explicit triggering conditions — 'when a result comes back with locked fields and the user asks why' and 'before sightglass_research_company' — and names the related sibling tool. When-to-use and a sequencing relationship are both spelled out, leaving little 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 the safety profile (readOnly, idempotent, non-destructive), yet the description adds genuinely non-obvious behavior: the call is side-effect-free for the user ('nothing is shown to the user yet'), it emits presigned media URLs intended for context loading, and it hands off a resultId to sightglass_show. That stateful handoff contract is the kind of detail 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?

Three tight sentences, front-loaded with what is fetched, then the user-visibility caveat, then the follow-up call. No filler and no restating of the name 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, so the description carries the return-shape burden and does so by enumerating the fields returned plus the media-URL capability. Combined with the resultId-to-show workflow, an agent has everything needed to call 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?

Schema coverage is 67%: projectId and workspaceId carry their own descriptions (Replo ids, plan selection, multi-workspace requirement) while adId is self-evident from the description's 'fetch one ad'. The description adds no syntax or format meaning beyond the schema, so the baseline 3 is right.

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 ('Fetch one ad in full') and enumerates the payload: copy, creative caption, duplication facts, landing page, and presigned media URLs. This clearly separates it from sightglass_find_ads (discovery) and sightglass_show (rendering), so an agent can route without opening the schema.

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

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

Gives explicit downstream guidance: 'Once you know the answer, call sightglass_show once with this call's resultId,' plus the clarifying note that show does not search again. It stops short of naming the upstream path (sightglass_find_ads to obtain an adId), so discovery-to-fetch sequencing 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 cover safety (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: plan-locked fields return null and are named in `locked`, `lockedCount` semantics, an instruction never to estimate locked data, that results are not shown until sightglass_show is called with resultId, and that no account is required. This is rare, high-value disclosure.

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 purpose and competitor scope, then workflow and plan caveats. Dense and mostly earning its place, though the show/resultId and auth instructions make it longer than strictly necessary for a single read 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?

No output schema exists, and the description compensates fully: it enumerates what comes back (category breadcrumb, Meta pages, grade mix, Momentum components) and explains the locked/lockedCount plan-gating and the show-vs-fetch split. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the schema already documents all three params. The description still adds semantic sourcing for companyRef (from search_companies or an ad's advertiser), which goes beyond the schema's brief 'Company id or slug.' projectId/workspaceId are left to the schema.

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

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

States a specific resource and scope — 'One company's full profile plus its six nearest competitors' — and enumerates the returned contents, making it clearly distinct from sibling sightglass_search_companies and sightglass_get_company_activity.

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 tells the agent where the reference comes from (id/slug from sightglass_search_companies or the companySlug on an ad's advertiser) and routes trend/launch history to sightglass_get_company_activity. 'Works without a Replo account: call it before asking the user to sign in' is a concrete when-to-use rule.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive). The description adds real behavioral context beyond that: window and charts are plan-gated, excluded fields return null and appear in each item's `locked` list, `lockedCount` signals more results on higher plans, the agent must report the plan limitation rather than estimate, and the result is not rendered until sightglass_show is called.

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 opens with the payload, then usage triggers, then plan/locked semantics, then the show handoff – a sensible front-loaded order. It is dense but every sentence carries information; a little tightening of the locked-field sentence would help.

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 a good job describing the return shape (trend, launch and longevity charts, tech stack) and the locked/null/lockedCount contract, plus the two-step show workflow. It stops short of explaining pagination or limits, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents days, weeks, companyRef, projectId and workspaceId with defaults and constraints. The description adds only the plan-capping idea for the trend/launch/longevity windows and the note that users say 'brands' for companies, which is marginal beyond the structured fields. Baseline 3 applies.

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

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

The description names the resource (one brand's advertising activity) and enumerates what comes back: daily active-ad trend, weekly launch counts, longevity buckets, and site tech stack with first-seen dates. That is specific enough to distinguish it from generic siblings like sightglass_get_company or sightglass_research_company, though it never names an alternative explicitly.

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

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

It gives concrete triggering questions ('is this brand scaling up or pulling back', 'what did they change') and an explicit follow-up protocol: after getting the answer, call sightglass_show once with this call's resultId, and it notes the show call does not re-search. When-to-use and the downstream step are both 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?

Beyond the readOnly/idempotent annotations, it discloses plan-gated behavior (locked fields return null and are named in the `locked` list, `lockedCount` shows how many more results a higher plan reveals), instructs the agent to say data is on a higher plan and never estimate it, and clarifies that results are not yet shown to the user. This is unusually rich 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?

Front-loaded with purpose and organized into output sections, semantics, plan behavior, and handoff. Nearly every sentence carries weight, though the density is high and it takes effort to parse compared to a truly lean definition.

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 fairly complex tool, the description compensates by describing the result sections, entitlement/locked behavior, the resultId handoff to sightglass_show, and the account requirement. An agent has everything needed to call and route 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 67% and the description adds real meaning: groupBy defaults to company, categoryId drives the categories-to-leaders drill-down and comes from this tool's own `categories` result. The `limit` and `weeks` params are left to the schema, so it stops short of full coverage.

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 (the market view: who holds what share of active ads, week by week) and enumerates the returned sections (pulse, share, categories, leaders). It clearly distinguishes itself from siblings like sightglass_show (display) and sightglass_find_ads (ad-level search).

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 the follow-up: call sightglass_show once with the resultId to render cards, and notes show does not search again. Also states it works without a Replo account and should be called before asking the user to sign in, giving clear ordering guidance.

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