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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the bar is lower. The description adds real behavioral context: output is a navigable menu whose URLs are meant to be copied into subsequent calls, and behavior differs based on whether menuUrl is supplied. No mention of limits or result shape, but the chaining behavior is disclosed.

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 correctly with purpose and routing ahead of the parameter mechanics. However, the eleven-item URL enumeration is bulky and largely redundant with what an agent would obtain by browsing the root menu (and with the schema's own example values), so not 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?

No output schema exists, so the description carries the return-value burden; it partially does so by framing responses as menus with links to copy forward. Combined with the routing rule and parameter guidance, an agent has enough to call and chain this tool correctly, though it never states what a response entry looks like.

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 3 is the baseline; the description goes further by explaining the omit-vs-pass semantics of menuUrl and supplying eleven concrete vertical URL examples that map directly to valid values. It adds meaning beyond the schema's generic example strings.

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 (browse the Wix REST API docs menu hierarchy) and immediately contrasts it with the keyword-search alternative by name. An agent can distinguish it from SearchWixRESTDocumentation 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?

Explicit when-to-use ('explore and discover APIs by navigating' vs 'searching by keywords') plus concrete how-to: omit menuUrl for top-level categories, pass menuUrl copied from a previous response to drill in. The alternative tool is named, and the drill-down workflow is 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?

No annotations are provided, so the description carries the full burden. It discloses that it acts on the visitor's behalf (implying possible mutations) and mandates the SearchSiteApiDocs prerequisite, which is useful. However, it never states read-vs-write consequences, error behavior, side effects, or auth failure handling beyond the token, leaving meaningful behavioral gaps for an unannotated tool that can perform arbitrary actions.

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

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

Front-loads the core purpose before the workflow guidance, and the emphasis on checking docs is well placed. There is mild redundancy between the description and the schema's url/visitorToken notes, but overall it is efficient and readable.

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 generic API-invocation tool with no output schema, the description gives the essential operating procedure (get URL from docs, never guess, reuse visitorToken). It is nearly complete; the only shortfall is the absence of any statement about what a call returns or how failures surface, which matters given the tool's open-ended nature.

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 url, body, method, and visitorToken in detail. The description reinforces the url provenance and token guidance but largely repeats the schema rather than adding new semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Call apis on site OhGiftPlease', names the target endpoint, and clarifies the intent ('perform an action on visitor's behalf, for example, query the site's data or book an appointment'). This is clear and lets an agent distinguish it from the docs-lookup siblings, though the tool is inherently generic ('any API') so it lacks tight scope boundaries.

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 workflow: 'Before calling this tool, you should ALWAYS check the rest docs (use SearchSiteApiDocs tool)' and 'NEVER try to guess the API or endpoint'. It names the alternative tool and the condition that routes to it, and pins down where the url param must come from. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true; the description goes well beyond them by disclosing the sandbox limits (no fs/path/node:* modules, no downloadable file creation), the auth model (visitorToken only, never set scope/siteId/Authorization), and error semantics (wix.request throws; use Promise.allSettled for independent probes). The one gap is the openWorldHint=false annotation, which sits awkwardly against a tool whose whole purpose is outbound calls to www.wixapis.com — the description never reconciles that, though it is not a direct contradiction.

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

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

It is front-loaded and clearly sectioned (preference, one-call recipe, code shape, auth, limits, errors), which is appropriate for a complex execution tool. However it runs long and several blocks — the CRITICAL CODE SHAPE rules, the no-fs/no-file rules, the visitorToken instruction — repeat content already carried verbatim in the input schema, so not 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?

There is no output schema, and the description compensates: it explains that the function's return value is what comes back, supplies a full multi-step worked example, and mandates that created-entity IDs be included in the returned object. For a sandboxed code-execution tool this leaves nothing material an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds meaning by explaining what belongs in sourceDocUrls (every docs/recipe URL relied on), the visitorToken reuse rule, and the docs-verification workflow that governs how `code` should be written. Much of the code-shape guidance duplicates the schema, which keeps it short of a 5.

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

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

States a concrete verb and resource ('Run JavaScript against the Wix REST API on site "OhGiftPlease"'), names the sandbox execution model, and explicitly contrasts itself with the sibling CallWixSiteAPI. An agent can distinguish it from every other tool in the set 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 when-to-use and when-not guidance: 'PREFER THIS TOOL OVER CallWixSiteAPI... fall back to CallWixSiteAPI only for a trivial one-shot read.' It also states the one-call-per-recipe rule, the read-only probing rule, and routes the agent to SearchSiteApiDocs before writing code — every alternative and precondition is named.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that a new visitor session is created and gives a strong operational rule against reusing the tool once a token is present, but it omits token lifecycle details such as expiration or whether a new call invalidates existing tokens.

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. The purpose is front-loaded, followed by the prerequisite and then the anti-reuse warning, 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 zero-parameter tool with no output schema, the description clearly states what is obtained (a visitor access token) and how it relates to CallWixSiteAPI. It could be slightly more complete by specifying the token's format or expected handling, but it covers the essential 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?

The tool takes zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed, and the schema is empty with 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: create a visitor session and obtain an access token. It names the exact site and API endpoint, and references the sibling tool CallWixSiteAPI to clarify its role in the workflow.

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 when to use the tool (before calling CallWixSiteAPI for the first time) and when not to use it (if a visitor token already exists in context). No inference is required.

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

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

With no annotations and no output schema, the description carries the full burden and largely meets it: it enumerates the complete return payload, including the feature list that gates other tools, which is essential behavioral context. It omits auth/permission requirements and error behavior, but for a zero-parameter public read of business metadata 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?

Three sentences, front-loaded with the resource and followed by the return contents, so an agent can stop reading early if it only needs the summary. The site URL and the repeated 'business' wording are minor padding but not enough to obscure the payload description.

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

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

Given a zero-param read with no output schema and no annotations, the description compensates by spelling out both the business fields and the site-feature list, which is what an agent needs to decide whether to call it and to interpret results. Only authentication and failure semantics are absent, which are not critical for this discovery call.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate and no syntax to explain. No misleading parameter guidance is present.

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 ('Get business and site details') and enumerates the returned fields (timezone, email, phone, address, schedule, etc.), so the agent knows exactly what it retrieves. It implicitly separates itself from siblings by noting the returned site features are consumed by other tools, but it never names those siblings, so differentiation is inferred rather than explicit.

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 it: 'when user asks for business contact details, or about what they can do on the site, or when you need to know what features are available on the site.' That is clear context with concrete triggers, but it gives no exclusions or named alternatives among the sibling docs/API tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description usefully adds that the returned article contains code examples for using the method, but adds little else about behavior or limits.

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

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

The tool-specific content is front-loaded and tight, but it is followed by a large block of generic agent-mandatory-instructions and multi-tool flow descriptions that are not specific to invoking this tool. This boilerplate inflates the definition well beyond what this fetch tool 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?

For a single-parameter read-only fetch with no output schema, the description covers what the tool returns (full article with code examples) and how to obtain the URL. That is sufficient, though return-format details are absent.

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 one parameter at 100% schema description coverage, the schema already documents the URL format including the ?apiView=SDK rule. The description repeats the REST-as-is / SDK-query-param guidance, adding no meaning beyond the schema, so baseline 3 applies.

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

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

The opening sentence gives a specific verb (fetches) and resource (full Wix docs article or method article) and notes it returns code examples, which distinguishes it from ReadFullDocsMethodSchema. It is clear, though sibling differentiation is only implied rather than stated by name.

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 to get the URL (user message or earlier tool result) and what to do when there is no URL (search or browse the docs first). This is actionable context routing, though it does not name the specific search/browse sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the description need not restate it. The description adds genuinely useful context: the fact that the alternative tool can avoid "dumping unrelated fields" while this one returns everything, plus the SDK query-param requirement. It does not mention rate limits, auth, or result size, so it exceeds the annotation floor only modestly.

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 first paragraph is front-loaded and tight, with the routing rule and URL conventions stated before the alternative. However, the definition is then padded with a very large block of generic agent-mandatory-instructions covering site management, WixREADME, and unrelated flows that do not earn their place in a tool that merely fetches a method 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?

There is no output schema, so the description carries the burden of explaining the return value, and it does so ("the entire request/response schema with all the fields and their descriptions"). Together with the explicit fallback positioning within the schema-based flow, an agent has enough to invoke it correctly; only return size or truncation behavior is unaddressed.

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

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

Schema description coverage is 100%, so both articleUrl and reason are already documented in the schema, establishing the baseline of 3. The description reinforces the URL format rules for REST vs SDK and implicitly frames reason as justification for the fallback, but adds no syntax or format detail beyond the schema.

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

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

The opening sentence states a specific verb+resource ("Fetches the full method schema for a given method") and immediately clarifies the payload ("entire request/response schema with all the fields and their descriptions"). It explicitly distinguishes itself from the sibling SearchWixAPISpec, so an agent can route between them 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?

It states when to prefer the alternative ("For REST API methods, prefer SearchWixAPISpec when it is available") and the precise fallback condition ("Use ReadFullDocsMethodSchema for REST only when SearchWixAPISpec is unavailable or did not provide the needed detail"). It also gives per-input URL conventions (REST as-is, SDK with ?apiView=SDK), 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?

No annotations are provided, so the description carries the burden. It discloses a genuinely important behavioral constraint — the tool DOES NOT support filters (e.g., 'under $10') — which is not derivable from the schema. It stops short of describing return format, result ranking, or auth requirements, so it is not fully complete.

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 intent and the four use cases are front-loaded, and the exclusion follows the inclusions in a logical order. The parenthetical in item 4 and the slight overlap between items 1 and 3 add minor redundancy but each sentence still 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, no-output-schema search tool, the description covers purpose, precedence against GetBusinessDetails and API tools, and the no-filter limitation. It could note that results are free-text site content, but nothing critical to invocation is missing.

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

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

Schema coverage is 100% and the single searchTerm parameter is well documented with examples ('working hours', 'store locations'). The description adds no syntax or format detail beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb (searches) and resource (the site 'OhGiftPlease') with the exact endpoint, and explicitly contrasts itself with the sibling 'SearchSiteApiDocs'. An agent can distinguish it from siblings 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?

Provides four enumerated when-to-use cases plus an explicit when-not-to-use rule naming the alternative tool to use instead for product/service searches. Nothing about routing is left to inference.

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

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

With no annotations, the description carries the full burden. It usefully discloses that malformed inputs (code, SQL, URLs, symbols) are rejected and return no results, which is real behavioral context, but it says nothing about authentication, rate limits, or the shape of the returned documentation.

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, but the description is bloated by chatbot persona framing ('You are a helpful OhGiftPlease site assistant chatbot') and repeats the input constraints twice — once in the example paragraph and again in the final paragraph.

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 one-parameter read tool with no output schema, the description covers what the tool searches, what it returns conceptually, and how to phrase input. Only the details of the returned documentation format are left unspecified, 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?

Schema coverage is 100% for the single searchTerm parameter, and the schema already documents it thoroughly with its own example. The description largely restates those same constraints and examples rather than adding new semantic detail, so baseline 3 is appropriate.

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

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

States a specific verb (Searches) and resource (site API documentation) and says it returns usage guidance. However, it does not differentiate itself from siblings like ReadFullDocsArticle, ReadFullDocsMethodSchema, BrowseWixRESTDocsMenu, or SearchInSite, so an agent must infer which docs-retrieval tool to pick.

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

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

Gives clear context (helping the user query site data or perform actions) and actionable query guidance, including examples and the fallback 'rephrase your search term'. It stops short of naming alternatives or stating when a different docs tool should be used instead.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuine behavioral context beyond them: the output contains linked documents that seed downstream tools, it is a one-time gate that need not be re-called, and it defines fallback flows when recipes are absent. It omits concrete return-format or size/pagination detail, but that is minor for a zero-param read tool.

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

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

The directive and exceptions are correctly front-loaded, but the body is heavily padded with repeated ALL-CAPS mandates ('MANDATORY FIRST STEP', 'NON-NEGOTIABLE') and the flow-description bulids duplicate the no-tool variants that add little for an agent already holding the tool. Content is mostly useful but not tightly sized.

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

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

For a zero-param gate tool with no output schema, the description covers what the agent needs: purpose, the mandatory-first-step protocol, all routing exceptions, and both with/without-tool execution flows. It stops short of describing the concrete shape of the returned context, but no output schema exists to require it.

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

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

The tool takes no parameters and schema description coverage is 100%, so the baseline of 4 applies. There is nothing for the description to clarify on the parameter axis.

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

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

The description states what the tool provides — foundational context (including linked documents) that grounds all other Wix tools — and explicitly distinguishes itself from siblings like GetSiteContext, ListWixSites, and UploadImageToWixSite. However, it never cleanly states the mechanical output (a recipes index), which is only inferable from the flow-description section rather than the opening directive.

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 rules plus named exceptions (new site creation, listing sites, image upload) with the correct alternative tool for each, and covers the mid-conversation re-entry case via GetSiteContext. This is model usage guidance — the agent knows exactly when to call this and when to route elsewhere.

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