agentready-mcp

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

Without annotations, the description discloses key behaviors: it returns multi-page synthesized answers with citations, auto-crawls for unindexed sites, and has a ~60s latency. It also indirectly indicates it is more robust than web_fetch for JS-rendered content. No annotations are present, so this is the primary transparency 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 sentences: opening purpose, numbered use-case list, and unindexed-site note. Every clause is informative, no padding, and the structure guides the reader from general to specific.

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

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

Given the tool's moderate complexity (3 params, no output schema), the description covers the core function, return value (cited answers), and edge case (auto-crawling). It does not need to explain return structure further.

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

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

Schema covers all three parameters (domain, query, url) with clear descriptions, and the description does not add parameter-specific guidance beyond what's already in the schema. The level of detail in the schema makes up for the absence of extra param 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 opens with a clear action ('Query any website's documentation') and outcome ('cited, multi-page answers in natural language'). It distinguishes from siblings by explicitly contrasting with web_fetch (for JS-rendered sites) and referencing submit_site as unnecessary when auto-crawling.

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 explicit use cases with examples (synthesis, JS-rendered sites, citations, speed) and notes when not to use it (for sites not indexed, it handles auto-crawling, so no separate submit_site call). This is strong guidance for selection.

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 transparency burden. It discloses the auto-indexing side effect and enumerates return values, which is useful. But it stops short of covering auth needs, rate limits, or potential errors, leaving gaps for a tool that may mutate state by triggering indexing.

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, information-dense sentence that covers the action, optional behavior, and return payload with zero filler. It is well-structured and easy to parse.

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

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

For a tool with one parameter and no output schema, the description covers purpose, a notable side effect, and return value contents. It is reasonably complete, though it lacks explicit usage alternatives and deeper behavioral caveats, which keeps it from a perfect score.

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 input schema already provides a full description of the domain parameter, including the ability to pass full URLs (100% coverage). The tool description adds no extra parameter context, 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 clearly states the tool's function: 'Return the AgentReady capability manifest for a website.' It lists the specific content of the manifest (freshness, read-only limits, schemas, MCP/HTTP endpoints), which distinguishes it from sibling tools like ask_site or refresh_site.

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

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

The description implies when to use it by noting it automatically indexes unindexed sites, so it's useful for capability discovery. However, it does not explicitly state when to prefer this tool over alternatives like refresh_site or plan_site_action, nor any exclusions.

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

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

The description discloses that the index 'grows as new sites are submitted', adding behavioral context. However, it does not mention output format, pagination, or other response traits. With no annotations, the description carries the full burden, and the coverage is minimal for a simple list 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 description is concise and front-loaded: the first sentence states the core action, and the second adds usage context and dynamic behavior. Every sentence earns its place without 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 simple no-parameter tool, the description covers purpose, usage, and dynamic growth. However, it does not specify what a listed 'website' entry looks like (e.g., URL, name), and there is no output schema to fill that gap. This is a minor but notable omission.

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

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

The tool has zero parameters, so schema description coverage is trivially 100%. Per the guidelines, a zero-parameter tool gets a baseline of 4, and the description does not need to compensate.

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

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

The description clearly states 'List all websites currently indexed in AgentReady' with a specific verb, resource, and scope. It also distinguishes from siblings by referencing the submission workflow and ask_site, making its role clear.

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 explicitly says 'Use this to check if a domain is already available before submitting it', providing a clear when-to-use. It references ask_site as a downstream tool for cited answers, but does not explicitly enumerate alternatives or exclusions.

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

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: read-only, auto-indexes if not indexed, never executes side effects, and identifies supported steps, sources, risks, and confirmation requirements. This is substantive transparency. A minor gap is lack of mention of error handling or what happens if indexing fails, but overall it's well-covered.

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

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

The description is two sentences, front-loaded with the primary purpose, and every sentence adds value. It succinctly covers the tool's function, auto-indexing behavior, and its non-execution guarantee without redundancy. Ideal length and structure.

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 has only two simple parameters, no output schema, and no annotations, so the description is the main source of context. It sufficiently explains what the tool does, how it behaves, and what it returns (steps, sources, risks, confirmation). It's nearly complete, though it could clarify the output format (e.g., text vs. structured data), which would make it a 5.

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 does not add meaningful parameter-specific semantics beyond the schema, but it doesn't need to given the high coverage. The description's mention of 'natural-language request' and 'site' aligns with the existing parameter descriptions.

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

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

The description clearly states the tool's function: turning a natural-language request into a grounded, read-only AgentReady plan for a website. The verb 'turn into' and resource 'website' are specific, and the mention of 'plan' distinguishes it from siblings like ask_site (which likely answers questions) and get_site_capabilities (which lists capabilities).

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 clear context for when to use the tool: for planning a request against a website in a read-only manner. It explicitly notes that it never executes side effects, implying it's for planning rather than execution. However, it does not explicitly state when not to use it or mention alternatives, so it stops 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?

With no annotations provided, the description must carry the full burden of behavioral disclosure. It states the action (rating) and the optional request_id detail, which adds context. However, it does not disclose whether the rating is stored, if it is reversible, or any side effects, leaving some ambiguity for a mutation-like operation.

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

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

The description is two sentences and front-loaded with the primary purpose. Every word earns its place, and the optional request_id guidance is concise. There is no redundancy or fluff.

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 rating tool with 4 parameters and no output schema, the description covers the essential context: what to rate, the rating scale, and how to associate the rating with the correct answer. It could mention prerequisites (e.g., an existing ask_site answer) or validation, but the high schema coverage 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 description coverage is 100%, so the baseline is 3. The description adds a useful hint about request_id ('returned in structuredContent') that is not fully present in the schema. It does not add significant meaning for domain or rating, as those are already described in the schema.

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

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

The description clearly states the verb 'Rate' and the resource 'a previous ask_site answer', with a specific quality scale (1-5). This distinguishes it from sibling tools like ask_site, list_sites, and refresh_site, all of which have different purposes.

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 clear context: it is used to rate a previous ask_site answer. It also instructs to pass request_id when available, which is a concrete usage guideline. While it does not explicitly mention alternatives or exclusions, the sibling tools are obviously different, so the intended use is unambiguous.

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

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

With no annotations provided, the description bears the full burden and does well: it reveals the operation takes '~60 seconds,' performs automatic initial indexing for never-indexed sites, and ensures 'ask_site returns fresh content' after completion. This gives the agent a clear expectation of side effects and outcomes.

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 concise, front-loaded with the core action, and every sentence adds value: the action, the auto-indexing behavior, the use case, and the duration/outcome. No redundant or vague language.

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

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

Given the lack of annotations and output schema, the description covers the important context: what the tool does, when to use it, how long it takes, and what the user can expect afterward. It could go deeper on potential failure modes or side effects, but it is reasonably complete for a simple single-parameter 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?

The sole parameter (domain) has 100% schema coverage with a clear example. The description itself does not add extra meaning to the parameter beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's primary action: 'Force a full re-crawl of a site to pick up new or changed content.' This is a specific verb (re-crawl) with a clear resource (a site). It also distinguishes itself from siblings by contrasting with ask_site, which queries existing content.

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

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

Provides explicit when-to-use guidance: 'Use when ask_site returns outdated information or when you know the site has recently been updated.' This clearly frames the tool's purpose relative to its sibling. It does not explicitly mention when not to use it, but the context is sufficient.

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 discloses the four-layer pipeline, ~60 second latency, and the fact that it handles JS-heavy sites. This adds meaningful behavioral context, though it could mention idempotency 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?

Three sentences, front-loaded with the primary action, and every sentence provides useful context (when to use, pipeline, timing, outcome). No unnecessary words or repetition.

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

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

Despite lacking annotations and an output schema, the description covers purpose, usage, process, duration, and post-condition. It doesn't describe return values or error handling, but for a single-parameter tool this is mostly complete and actionable.

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 covers the only parameter 'url' with a clear description and example. The tool description adds context about the URL's role in indexing and JS-rendered sites, but doesn't add new formatting or semantic details 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 description clearly states the tool indexes a website so it can be queried with ask_site. It uses a specific verb+resource construction and distinguishes itself from siblings like list_sites and ask_site.

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

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

Explicitly says 'Use this when the site is not yet in list_sites' and contrasts with web_fetch for JS-rendered pages. Also implies ask_site is for querying after indexing, providing clear when-to-use guidance.

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