Site MCP

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful behavior beyond that: it returns metadata only, not page text, and lists the exact metadata fields, which is valuable given there is no output schema.

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

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

Two tightly written sentences with no waste. The resource scope and the 'without full text' distinction are front-loaded, followed by the field list and usage 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 a one-parameter read-only metadata tool with no output schema, the description supplies the return fields and the triage use case. Minor omissions, such as default path behavior and not-found handling, keep it from being fully complete.

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

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

Schema description coverage is 100%, and the single path parameter is already well documented in the schema ('Exact path or full URL... Never guess'). The description adds no parameter-specific syntax or edge-case guidance beyond what the schema provides, 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 resource ('Metadata for one page on https://sitemcp.dev/') and explicitly excludes full text, enumerating the fields returned. It distinguishes itself from read_page by scope, though it does not name 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 condition: 'Use it to decide whether a page is worth reading.' This implies triage before read_page, but it does not explicitly name alternatives or 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 cover safety (readOnlyHint=true) and scope (openWorldHint=true), so the bar is lower; the description adds the concrete return contents and the important disclosure that the call is optional and not a prerequisite. With no output schema, enumerating the returned fields is genuinely load-bearing information. It doesn't mention cost, latency, or caching, but nothing material is missing for a zero-parameter read.

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

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

Two sentences, front-loaded with the resource and its payload, then the optionality caveat. No filler or restatement of the name.

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

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

Given zero parameters, no output schema, and annotations covering safety, the description supplies nearly everything needed: what comes back and whether to bother calling it. The only gap is not stating how this differs from get_page_info for an agent choosing between them.

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, so the baseline is 4. The description correctly implies no inputs are needed by framing the tool purely as orientation output.

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

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

States a specific resource ('Orientation for https://sitemcp.dev/') and enumerates the payload: title, description, language, sitemaps, robots.txt, pages discovered, search-index status. It is clear this is a site-level summary, though it never explicitly contrasts itself with the adjacent get_page_info, so the site-vs-page distinction is left to inference.

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?

'Optional; not required before research' gives an explicit when-not, which is useful. However, there is no positive guidance on when this tool is the right choice over siblings like list_pages or search_site, and no named alternative workflow is routed to.

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 removal of the safety burden in that regard. The description adds useful behavioral context beyond the schema: it returns link text and an internal/external classification, and it is positioned as a navigation aid rather than a raw scraper.

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. The first sentence front-loads what the tool returns, and the second gives concrete usage guidance. Every phrase adds value.

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 read-only tool with optional parameters, the description is complete: it names the page scope, the returned fields, and the intended use case. Even without an output schema, an agent knows what to expect and how to use the two 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?

The schema already describes path and gives scope an enum with a default, so the description does not need to re-explain them. With 50% schema coverage, the description only mildly reinforces the 'one page' idea and does not add direct parameter detail beyond what the schema provides.

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

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

States the exact resource (one page on sitemcp.dev) and the precise output: every link with its text and whether it stays on the site. This clearly distinguishes it from siblings like list_pages, which would list pages rather than links.

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 use it for navigating the site instead of guessing URLs, which gives a clear positive use case. It does not enumerate when to prefer siblings like read_page or search_site, but the instruction is practical and unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context about the source ('from its sitemap, or links on the homepage'), but does not disclose other behavioral traits such as pagination, ordering, or whether results may be incomplete or dynamic.

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 a single front-loaded sentence with no filler. The parenthetical about the data source is valuable and earns its place, and the description remains appropriately compact for a simple 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?

For a low-complexity, optional-parameter tool with read-only and open-world annotations, the description is mostly complete: it states the action, resource, and source. It lacks usage guidance relative to siblings and an explicit statement of return format, but the phrase 'List page URLs' reasonably covers the return value.

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 50%: filter has a schema description, but limit has only numeric constraints. The description adds no meaning for either parameter, so it fails to compensate for the undocumented limit parameter or enhance understanding of how filter interacts with the URL list.

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

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

The description clearly identifies the action ('List') and resource ('page URLs on https://sitemcp.dev/'), which is specific and useful. However, it does not explicitly differentiate from the sibling tool list_links; the reader must infer that 'page URLs' and the sitemap/homepage source distinguish 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?

The description provides no guidance on when to use this tool versus alternatives like list_links or search_site. It states a data source, but no conditions, exclusions, or preferred scenarios are given, so an agent receives no routing help.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavior: a live fetch, Markdown output, source-link citation, read and last-changed timestamps, and offset pagination for long pages. It does not cover rate limits or error behavior, but it goes well beyond the annotations.

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

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

The description is four compact sentences and front-loads what the tool returns. The citation instruction and pagination note are useful rather than filler. The phrase 'Returns with when it was read' is slightly awkward, which keeps it from a 5.

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

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

There is no output schema, so the description must explain the return shape, and it does: main content as Markdown, a source link, read time, last-changed time, and offset pagination. It could say more about error handling or what counts as 'main content,' but it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reiterates offset pagination for long pages but adds no syntax, format, or path-resolution detail beyond what the schema provides. Baseline 3 is appropriate when the schema handles parameter semantics.

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

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

The description states a specific verb and resource: 'Fetch a page ... live and return its main content as Markdown.' That is clear enough for an agent to distinguish reading page content from sibling tools like get_page_info or list_pages. It does not explicitly name a sibling for differentiation, 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?

The description implies the tool is for reading a page's live content, but it gives no explicit when-to-use or when-not-to-use guidance relative to siblings such as get_page_info, search_site, or research_pages. It also does not explain when to paginate with offset beyond a passing mention.

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 readOnlyHint/openWorldHint annotations, the description discloses the mechanism (URLs discovered from the site's sitemap, pages read concurrently), the return payload (Markdown citations plus page text including live product variants), and a hard behavioral guardrail ('Never guess paths'). No behavior is left for the agent to infer.

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

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

Front-loaded with the selection claim, then mechanism, then return format, then guardrails. Every sentence adds information the agent needs (routing, output expectations, anti-hallucination rule) 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 2-parameter, read-only, no-output-schema tool, the description covers purpose, mechanism, and return shape well enough to call it correctly. The gaps are minor: no explanation of 'pages_per_query' and no indication of what happens when a query matches nothing.

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 'queries' well ('one short page-title/topic query per item'). However, 'pages_per_query' is never mentioned, leaving the agent to discover the 1-3 depth control 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 (research/compare) and resource (multiple pages on sitemcp.dev), plus scope ('several topics', 'concurrently in one call'). The contrast with 'separate search/read calls' implicitly separates it from siblings search_site and read_page, so an agent can pick it 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?

'Best tool for comparing or researching several topics' establishes the selection condition, and 'No separate search/read calls are needed if the requested facts are present' rules out chaining search_site + read_page. It never explicitly names the sibling to use for a single page, so the alternative routing 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description goes beyond them by disclosing the return shape — matching pages with snippets, plus both the read timestamp and the page's claimed last-changed time — which tells the agent how freshness can be judged.

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

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

Three short sentences with no filler: purpose first, the alternative second, the return format last. Every sentence carries distinct information an agent can act on.

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 covers the return payload and freshness fields, and it names the multi-topic alternative. The remaining gap is result-count control (max_results) and what happens when nothing matches, which an agent may need before calling.

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

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

Schema description coverage is 0%, so the description must carry the burden, yet it only implies what 'query' means and says nothing about max_results — no mention of the default of 5, the cap of 10, or the effect on result count. Query syntax and matching behavior are also left unexplained.

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

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

The description uses concrete verbs (discover, search) and names the resource and target site (https://sitemcp.dev/), so it is clearly a site search tool. It is slightly muddled by claiming both URL discovery across the sitemap and query-relevance search, but the sibling differentiation from research_pages keeps it 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?

It explicitly routes the agent away from this tool when multiple topics are involved: 'For multiple topics use research_pages instead.' That is a real when-not condition with a named alternative, though no other siblings (read_page, list_pages) are addressed.

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 readOnlyHint/openWorldHint annotations, the description discloses the return payload (links, live stock, prices, descriptions, feature excerpts), that shortlisted reads happen concurrently, the scope limit (stores exposing a public Shopify catalog), and that errors explain the fallback. No contradiction with readOnlyHint. It stops short of noting rate limits or result freshness/caching.

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

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

Five sentences, front-loaded with the primary purpose and followed by filtering behavior, return contents, and the citation instruction. Mostly earns its place, but the opening keyword list and the 'supports stores exposing a public Shopify catalog' sentence could be tightened.

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

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

With no output schema and 6 parameters at 67% schema coverage, the description does the necessary work: it explains what one call returns, the Shopify-only scope, and error behavior, plus a downstream citation requirement. Minor gaps remain on currency/limit semantics, but nothing required 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 67%, and the description reinforces the two most error-prone parameters: it stresses 'exact size' (matching the schema's 'never substitute another size') and clarifies max_price is an exclusive ceiling. It adds no meaning for audience, limit, or currency, which the schema already partially documents — marginal but real added value.

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 — filters the public store catalog by variant availability, exact size and price ceiling, then reads shortlisted product details — and the title names the outcome (in-stock products, price comparison). It is distinguishable from siblings like search_site or read_page, though the opening clause ('shopping, shoes, product comparisons and recommendations') is keyword-stuffed rather than precise.

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 positions itself as the 'FIRST tool for shopping' and says to use it 'instead of guessing product names or repeated research/search/read calls,' which points at sibling tools without naming them. It lacks an explicit when-not condition (e.g., for non-Shopify stores beyond the fallback error note), 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.