Stormap

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral value beyond that: it enumerates the pass/fail checks performed, the output shape (0-100 score, letter grade, prioritized fix list), and the notable scoring policy that blocking bulk training crawlers does not lower the score.

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

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

A single front-loaded sentence that opens with the core purpose before listing checks and outputs. Dense but every clause carries information; the parenthetical check list is long yet earns its place by defining the score's meaning.

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 correctly compensates by describing the return contents (score, grade, checks, fix list) and the scoring caveat. Combined with annotations covering the safety profile, an agent has nearly everything needed; only alternative-tool routing is 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 a single parameter at 100% schema description coverage, the schema already documents the URL and even supplies examples. The description adds no further format or constraint detail, 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 and resource — scoring how well AI assistants can find, read and cite a public web page — and enumerates the concrete checks and outputs, which implicitly distinguishes it from the narrower siblings check_ai_crawler_access and generate_ai_robots_txt.

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 (audit a page for AI visibility), but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as check_ai_crawler_access for a robots.txt-only check. Adequate but leaves the agent to infer the decision boundary.

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 safety is covered. The description adds real behavioral context beyond that: it fetches robots.txt, inspects specific on-page signals, and returns a 0-100 score with findings. It omits rate limits, caching, or failure modes for unreachable URLs.

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 dense sentence with the purpose front-loaded, followed by the return shape. Every clause carries information — crawler list, eligibility check, readability signals, outputs — 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 by describing the return value (0-100 score plus findings list), and the single input is fully covered by schema and annotations. Only lack of guidance on siblings and edge cases keeps it from 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?

Only one parameter with 100% schema coverage, so the schema fully documents the url field and the baseline is 3. The description's phrase 'public URL' slightly reinforces the input constraint but adds nothing the schema does not already say.

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 (check) and resource (AI crawler access to a URL), names all eight crawler user-agents checked, and enumerates the readability signals inspected. This is far more specific than the title, though it does not explicitly differentiate itself from siblings like ai_visibility_score or generate_ai_robots_txt.

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 description — you call it to learn whether AI crawlers can reach a page and how machine-readable it is — but there is no explicit when-to-use, when-not-to-use, or named alternative among the 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 and openWorldHint=false; the description reinforces this with 'No network access,' which is genuinely useful for an agent reasoning about side effects. It does not, however, disclose the output shape or whether generated rules are written anywhere.

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 purpose and then the parameter inventory; every clause maps to real behavior. The dense parenthetical list of options is efficient rather than padded, though it reads as a run-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 7 parameters, no required fields, no output schema and near-zero schema coverage, the description covers the option space but omits what the tool returns (raw robots.txt text vs. a file), how site_url interacts with the generated rules, and whether output is persisted. Adequate but with visible 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 only 14% (just the `overrides` example), so the description carries most of the burden and does so well: it explains the policy enum values, per-bot overrides, allow/disallow paths, sitemap and crawl delay. It leaves `site_url` and path formatting unaddressed, so it is not fully compensating.

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 ('Generate robots.txt rules for AI crawlers') and scopes it by input policy. It is clear but never names or differentiates itself from the sibling generate_llms_txt, so an agent must infer which generator 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?

The policy definitions (open/balanced/block) implicitly tell an agent which mode suits which intent, but there is no explicit when-to-use guidance, no prerequisites, and no statement of when to prefer this over generate_llms_txt or check_ai_crawler_access.

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/network profile is covered. The description adds genuinely new behavior: the fallback that missing inputs are filled from the homepage and sitemap.xml, and a return-value summary ('file text plus notes'). No contradiction with the annotations.

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

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

Three tight sentences, front-loaded with the verb and artifact, then behavior, then return. Nothing redundant, though it could be marginally leaner.

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

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

No output schema exists, and the description compensates by describing the return (file text plus improvement notes). The main residual gap is the undocumented max_pages/site_name parameters, but overall an agent has enough to invoke 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?

With 60% schema coverage, three of five parameters are already documented. The description adds meaning beyond the schema by explaining how site_name, summary and pages are consumed together and how omissions fall back to sitemap.xml. It leaves max_pages and site_name unaddressed, keeping 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 specific verb and artifact: 'Generate an llms.txt file (llmstxt.org format) for a public website.' That is concrete and distinguishable from the robots.txt sibling by the named output format. It stops short of explicitly contrasting itself with generate_ai_robots_txt, so it is clear but not sibling-differentiating.

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 'for a public website' scoping implies when it applies, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives among the siblings (check_ai_crawler_access, generate_ai_robots_txt). Usage is inferable rather than 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the response is clean Markdown with front matter containing title, URL, dates, and tags — valuable since no output schema exists. It omits any note on truncation or auth/rate 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?

Two sentences, front-loaded with the core action and output shape, then the accepted input forms. Every clause carries information; nothing is 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?

Return format is adequately covered despite the absence of an output schema, which is the main thing an agent needs here. Missing pieces are the max_chars truncation behavior and any routing guidance versus search_guides, so it is complete enough to call but not complete enough to choose confidently.

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

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

Schema coverage is 50%: slug is documented in the schema, and the description usefully reinforces it with a concrete slug example and the accepted stormap.ai URL form. However, max_chars is undocumented in both places, and its truncation semantics are never explained — a meaningful gap the description fails to compensate for.

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 ('Return one Stormap guide') plus the output format, which cleanly separates it from the sibling search_guides by scope (one vs. many). It never names the sibling or an alternative, so 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 word 'one' plus the accepted slug/URL input implies the retrieval use case, but there is no explicit when-to-use guidance and no mention of when to prefer search_guides instead. Usage is implied rather than directed.

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=false, so safety is covered. The description adds valuable behavior beyond that: it enumerates the return payload (titles, URLs, Markdown URLs, short descriptions), which matters since no output schema exists. It does not mention result limits or pagination behavior.

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

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

Two tight sentences, front-loaded with what is searched and what comes back, then the handoff to get_guide. No filler or restated name/title.

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

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

With no output schema, the description compensates by listing return fields, and the read-only annotation plus the get_guide handoff cover the rest. Minor gaps remain around result limiting and category usage, but nothing blocks a correct invocation.

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

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

Schema coverage is 67%, so the schema already documents query and category with examples; the description's topic list loosely overlaps with the category filter but adds no syntax or semantics for limit or category. Baseline 3 is appropriate when the schema does most of the parameter 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 (Search) plus the resource (Stormap's practical guides on building with AI agents) and enumerates the topical scope. It also names the sibling get_guide for reading a result, so an agent can distinguish it from get_guide 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 get_guide to read one" explicitly routes the agent to the follow-up alternative and implies search is for discovery. There is no explicit statement of when not to use it or of prerequisites, 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.