DevDome Analytics

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description goes beyond them by disclosing the state transition (site stays pending), the artifact returned (verify_file_path + verify_content), and where that artifact is served (/.well-known/devdome-analytics.txt) — real behavioral context. It stops short of mentioning idempotency or what happens on a duplicate domain.

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 compact sentences, front-loaded with the action and followed by the post-condition and return artifact. No filler or restatement of the 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?

There is no output schema, and the description compensates by naming the returned verification fields and their serving path, plus the pending-until-verified state. It omits auth/permission requirements and behavior on an already-registered domain, but for a one-parameter create tool this is nearly 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?

With a single parameter at 100% schema description coverage, the schema already carries the meaning of 'domain' including the bare-domain format example. The description adds no syntax, normalization, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add a website to the account') and immediately differentiates itself from the read-oriented siblings (list_sites, get_stats) by describing the create action and its verification lifecycle. An agent can tell this is the entry point for onboarding a new domain without opening the schema.

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

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

The lifecycle clause ('the site stays pending until verified') gives clear context that this is the first step of a two-step flow, implicitly routing to verify_site. However, it never names verify_site as the alternative/next tool, so the routing is left to inference rather than stated explicitly.

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 on top: answers come from public resolvers (Cloudflare 1.1.1.1), cached results can lag a DNS change by its TTL, and whois data comes from the public RDAP registry. It stops short of discussing failure modes, rate limits, or behavior for non-existent domains or failing DKIM selector lookups.

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 enumeration of check modes, and nearly every clause maps to a distinct mode or caveat, so little is wasted. It is a dense wall of parenthetical clauses crammed into one paragraph, which costs a bit of scannability but not accuracy.

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

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

For an eight-mode tool with no output schema, the description explains what each mode yields (records, registrar/status/expiry, issuer/expiry/days-left, hostname behind an IP), which is what an agent needs to choose and trust the call. Minor gaps remain on error/empty-result behavior and the exact shape of each mode's response.

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 80% schema coverage the baseline is 3, and the description earns a bump by explaining behavior the schema cannot: default record type A, the fallback selector list tried when dkim_selector is omitted, and the mode-to-parameter binding (ip for reverse_dns only). The `domain` parameter still only gets 'bare domain' from the schema, so the description is not fully exhaustive.

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 (live DNS/domain checks) and enumerates the exact resource facets it returns (records, SPF/DMARC/DKIM, registrar/expiry, certificate, PTR). It explicitly scopes itself to 'ANY public domain (not only account sites)', which separates it from the account-oriented siblings like get_site_health and verify_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?

Maps each `check` value to a concrete use (dns = one record type, mx/ns/txt = that record set, email_auth = SPF+DMARC+DKIM, whois, ssl, reverse_dns), so the agent knows which mode to pick. It also names the alternative for account sites — 'get_site_health already holds the daily audit' — giving an explicit when-not-to-use route.

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

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

Annotations cover readOnly/openWorld, and the description adds substantive behavior: one request per call, no page content returned, redirect chain capped at 10 hops, http followed to https, and per-header pass/warn/fail verdicts. These are cost and output-shape facts an agent cannot derive from the annotations alone.

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

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

Front-loaded with the core verb and scope, then the mode breakdown, then the sibling caveat. Dense but every clause carries information; the semicolon-delimited mode list is efficient though slightly hard to scan.

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

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

With no output schema, the description carries the full burden of describing return values and does so per check mode, including hop limits and artifact scope. Nothing needed to call it correctly appears 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 50% because the 'check' enum has no description; the prose compensates fully by defining what each enum value returns (status code/final URL/timing/headers, hop-by-hop chain, security-header audit with pass/warn/fail). It also restates and clarifies the https-only URL constraint.

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 ('Live HTTP check of ANY public https URL') and enumerates exactly what each of the three check modes returns. It explicitly distinguishes itself from get_site_health, a close sibling, so an agent can select between them 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?

Gives one explicit alternative and the condition selecting it: for an account site's homepage, get_site_health already has this data from the daily audit. It also implies scope by restricting to public https URLs, but provides no general when-not guidance or exclusions for the other listed checks.

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

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

Annotations already declare readOnly, idempotent, closed-world, so the safety profile is covered. The description adds genuine value beyond them: nothing is fetched or stored, the response carries the file text plus a filename plus the warnings the tool page would show, and inputs the web page rejects are rejected here too. That last point is useful predictable-failure information, though quotas/size limits are unstated.

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?

Length is justified by 24 parameters and four distinct modes, and the lead clause front-loads the core purpose before the kind breakdown. The single run-on sentence with '=' separators is dense and harder to scan than a short bulleted breakdown, but no clause 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?

With no output schema, the description still explains the return payload (file text, filename, warnings) and the refusal behavior, and it covers all four mutually exclusive modes and their required inputs. An agent can call this correctly for any kind without further information.

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

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

Schema coverage is 0%, so the description must carry the full burden, and it largely does: it maps preset and rule names, code values (301 default/302/307/308), www add-or-strip with domain, the redirects [{from,to}] shape, the utm parameter set with normalize semantics, and the llms.txt structure (title, summary, details, sections with links). Nearly all 24 parameters gain meaning beyond their bare names and types.

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 ('Generate a ready-to-use file or link') and then enumerates the four concrete artifacts it produces (robots.txt, .htaccess redirects, UTM URL, llms.txt) with their build inputs. This clearly distinguishes it from every sibling tool, which are all analytics/lookup/inspection tools.

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

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

The per-kind enumeration effectively routes the agent: pick the kind whose described output matches the need. It also states the operating context ('nothing fetched or stored', 'the same output as the free DevDome tools'), which tells the agent this is a static generator rather than a live-data call. No explicit when-not-to-use statement against a named alternative, but none of the siblings overlap functionally.

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 by structured data. Beyond that the description adds only the semantic distinction between the two bot categories; it says nothing about the time window defaults (days vs from/to), pagination, or what a 'report' row contains. With annotation coverage this is an acceptable but thin contribution.

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, densely packed, with the core purpose front-loaded before the kind taxonomy. No filler, though the hyphenated phrasing is slightly telegraphic and reads more like a fragment than a complete instruction.

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 seven parameters including a nested filter object, the agent still cannot tell what the report returns (per-bot rows? aggregates? which fields?) or how the window is determined when only site is supplied. For a parameterized reporting tool with a nested filter object, the description leaves substantial operational questions unanswered.

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

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

Schema coverage is only 43% across 7 parameters including a nested filters object, so the description needs to compensate and largely does not. It adds real meaning for 'kind' (catalog bots vs behavioral threats, beyond the bare enum), but leaves site, to, days, and the ambiguous relationship between days and from/to entirely unaddressed in prose.

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

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

The description names a specific resource ('bot traffic on a site') and explains the human-vs-bot split DevDome performs, which lets an agent distinguish this from analytics tools like get_stats or get_breakdown. It never states a retrieval verb explicitly, but the resource scope is clear enough to identify the tool.

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 sentence 'kind bots = known-bot catalog activity; threats = suspicious/behavioral detections' effectively tells the agent which mode to choose for which question, which is genuine usage guidance. However, there is no guidance on when to call this versus get_stats, get_breakdown, get_visitors, or lookup_bot, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description earns credit for disclosing a non-obvious behavior: the countries/regions/cities dimensions silently ignore the page, referrer, campaign, event and goal filters. It does not disclose defaults for the date window (from/to vs days), the limit default, or whether absent dimensions return empty results.

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 dense sentences, front-loaded with the core purpose, and the dimension prerequisites precede the filter-caveat elaboration. The parenthetical about country-scoped views is slightly awkward but carries real information, so nothing is wasted.

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

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

For a 9-parameter tool with a nested filters object, an enum, and no output schema, the description covers the trickiest interactions but leaves the date-window parameters and result limit unaddressed. An agent can call it, but may guess wrong on the time range and row count.

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 33%, so the description must compensate and does so selectively: it explains country/region coupling to dimensions and the filter-ignore rule. However site, dimension, limit, days, from, and to are left entirely unexplained in both places, so the two required parameters and the result-size control are undocumented.

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

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

States a specific verb+resource pair ('Top-N breakdown of a site's traffic by one dimension') and names the dimension enum as the axis of variation, which is more specific than the sibling list_sites/get_stats names. It does not, however, say how this differs from get_stats, get_timeseries, get_paths, or get_visitors, which all sound like traffic reporting too.

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 gives real conditional rules for dimension-specific parameters ('regions needs country; cities needs country and takes region'), which is genuine usage guidance. But there is no statement of when to reach for this tool versus get_stats or get_paths, and no note that exactly one dimension is broken down at a time or how many rows are returned.

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 useful behavioral context beyond annotations: it names the event source (devdome('event', name) or plugin event tracking) and discloses that output is aggregated to one row per event name with counts for the window.

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

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

Two sentences, front-loaded with the core purpose and return shape, with the second sentence adding a useful linkage to the event filter. There is 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 six-parameter tool with nested filters and no output schema, the description gives a basic return-value summary and one parameter linkage, but it omits usage differentiation from siblings and does not explain the window parameters. It is minimally adequate but leaves meaningful 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?

With only 33% schema description coverage, the description must compensate but largely does not. It does clarify that event names populate the filters.event parameter, but it leaves top-level parameters like site, to, days, and limit unexplained beyond the schema, and it does not define how the window is formed.

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 resource ('Custom events the site sends') and return shape ('one row per event name with counts for the window'), which distinguishes it from generic analytics siblings like get_breakdown or get_stats. It does not explicitly say how it differs from every sibling, but the custom-event focus is 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 notes that 'Event names feed the event filter,' which implies a use case, but it gives no explicit when-to-use guidance, no when-not-to-use guidance, and no alternatives among the many sibling reporting tools. An agent must infer that this is for discovering event names rather than for general traffic reporting.

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 real context beyond that: results are scoped to a time window, counts are split into human and bot visitors, and each row exposes the goal id needed for downstream filtering. Missing only things like empty-result behavior or whether unconfigured goals appear.

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 return content is front-loaded ('saved goals ... with how many human and bot visitors completed each one'), and the goal-type enumeration earns its place by defining ambiguous terms like 'page' and 'click'. The sentence is dense but has 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 does a fair job describing row content (goal id, human/bot counts, goal type). However, for a tool with a nested filter object and three window parameters, it leaves the agent guessing about how to scope the report and what happens when filters are omitted.

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 40%, with five parameters including a nested filters object, so the description needs to compensate. It says only 'in the window', vaguely implying from/to/days, and never explains the filters object, the 'to' parameter, or how goal-type strings relate to filter values. The page/click/event/scroll detail describes returned row types rather than input parameters.

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

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

States a specific resource and result: the site's saved goals plus human/bot completion counts within a window, and even names the UI location (Website Settings > Goals). It also enumerates the four goal types, which makes it clearly distinguishable from siblings like get_events or get_breakdown. It stops short of naming those siblings explicitly.

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

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

Usage is only implied: the agent can infer this is the report to call for goal conversions, and the closing line hints the returned id feeds the goal filter. There is no explicit 'use this instead of X when...' routing, nor any note on prerequisites such as goals having been configured.

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 needs no restating. The description adds genuinely useful behavior: the window is fixed and non-negotiable, timestamps are UTC, and the payload is per-hour metrics — preventing an agent from attempting date parameters.

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

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

Two short sentences, no filler, with the window and grain front-loaded and the exclusion clause last. Every fragment 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 two-parameter read tool with annotations and no output schema, the description covers grain, window, timezone, and the metric set. The residual gap is the undocumented required `site` argument and whether filters narrow all metrics uniformly.

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% and the required `site` parameter has no description in either the schema or the description text. The only parameter-adjacent content is the negative statement 'no days/from/to'; the rich nested `filters` semantics live entirely in the schema, so the description contributes essentially nothing here.

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?

Names the exact resource and grain — hourly buckets over the last 24 hours — and enumerates the returned metrics (visits, visitors, pageviews, clicks, bots). The clause 'Fixed window, no days/from/to' implicitly separates it from range-taking siblings like get_timeseries and get_stats, though it never names an alternative outright.

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 fixed-window constraint implies when this tool applies (quick last-24h view) versus range-based tools, but no sibling is named and there is no explicit 'use X instead when you need Y' guidance. The agent must infer the routing from sibling names alone.

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, and the description adds real behavior: newest-first ordering, the returned field set, and the before/has_more paging contract. It stops short of stating default result volume or empty-site 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 with the resource and return shape front-loaded, then paging. Every clause carries information, though 'failing status' is terse enough to be slightly ambiguous.

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

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

With no output schema, the description does the necessary work of enumerating returned fields and ordering, and it covers the only non-obvious parameter interaction (has_more/before). Missing only site-identifier expectations for a 3-parameter read tool.

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

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

Schema coverage is 67%; limit and before are already documented in the schema, and the description's 'pass the started_at of the last row as before' largely restates the schema. The required site parameter remains undocumented in both places, with only 'of a site' as a hint.

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 (downtime incidents for a site) plus ordering, the fields returned, and the pagination model in one compact sentence. It is clearly distinguishable from data-analytics siblings like get_stats or get_events, though the verb itself is implicit.

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

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

Explains how to page but never says when to choose this over get_site_health or get_events, nor whether a time range or site-identifier format is required. The only usage instruction is the pagination rule.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a real behavioral trait – output is per-visitor with an ordered sequence of subsequent steps, implying high-cardinality, ordered rows – but says nothing about pagination/limit behavior or how many steps are returned. With annotations carrying the safety profile, a 3 is appropriate.

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 the core meaning front-loaded. The closing clause on `page` duplicates the schema description and is the only wasted content.

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 7-parameter tool with a nested filters object and no output schema, the description is thin: it never explains the time window parameters, how `limit` truncates the per-visitor paths, or whether filters narrow the entry cohort or the subsequent steps. An agent can call it, but cannot confidently predict what it gets back.

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 43% across 7 parameters (including a nested filters object), so the description needs to compensate and does not. It only restates `page`, which the schema already documents verbatim ('Entry page path, e.g. /pricing'), leaving the date window (from/days/to), `to`, and `limit` 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?

States concretely what the tool returns: visitors who entered on one page, plus the step-by-step path they took afterwards. That is a specific verb+resource combination (entry-page journey paths) that separates it from get_visitors and get_timeseries. It does not explicitly name a sibling or state how it differs from inspect_page, which keeps it below 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?

There is no when-to-use/when-not guidance, no mention of prerequisites, and no routing to alternatives such as inspect_page or get_visitors for related questions. The only implied context is that you must supply an entry page, which is already visible in the schema.

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, so the description's main addition is the 5-minute freshness window and the page/path fields it returns. That is useful context that goes beyond the annotations, though it does not discuss list shape, counts, or any operational quirks.

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

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

One compact sentence with no filler; the defining temporal constraint is front-loaded and every word adds 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?

For a simple one-parameter, read-only tool, the description covers what is returned (active visitors with page/path) and the relevant time window. It does not detail the site parameter or return format, but no output schema exists and the tool's complexity is low, so the remaining gaps are minor.

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

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

The sole required parameter, site, has no schema description, and the description only refers to 'the site' in passing. At 0% schema coverage, the description needed to define the parameter but does not, leaving the agent to infer that site is a site identifier.

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 identifies the resource (visitors) and a unique temporal scope (active in the last 5 minutes), plus the fields (current page and path), which distinguishes it from tools like get_visitors and get_stats. It is phrased as a noun phrase rather than an explicit verb, but the title 'Get Realtime Visitors' supplies the action, so the purpose is unambiguous.

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

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

The 'last 5 minutes' phrasing implies this is the realtime/current-visitors option rather than a historical tool, but it never names get_visitors or get_timeseries as alternatives or states when not to use it. The guidance is limited to inferred context.

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, and the description adds meaningful behavioral context: the response is deliberately compact, the raw 24h probe list and scanner file list are omitted, and 'days' means the last 30 daily uptime rows. That truncation disclosure is exactly the kind of thing annotations cannot express; only the lack of any latency/limit framing keeps it from a 5.

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

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

The payload content is front-loaded in the first clause and the caveats (what is dropped, what 'days' means, where to go for older incidents) follow in a compact trailing block. It is dense but every sentence carries information; only the run-on structure slightly hurts scanning.

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 must convey the return shape, and it does so thoroughly, including the deliberate omissions. The remaining gap is parameter format for 'site', which is the one thing an agent needs in order to call it correctly and is not covered anywhere else.

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

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

Schema description coverage is 0% for the single required 'site' parameter, so the description must carry the burden. It only says 'for a site' and never clarifies whether the value is a domain name, a hostname, or an internal site ID, nor does it give a format example, which leaves ambiguity that could cause a failed call.

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 resource (site uptime/health) and enumerates exactly what the summary contains: status, response time, TLS/domain checks, open incidents, latest daily audit, and Malware Scanner roll-up. It also distinguishes itself from the sibling get_incidents by scope, so an agent can select it without opening the schema.

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

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

It explicitly routes paging through older incidents to get_incidents, which is a concrete alternative and condition. However, it gives no guidance on when to prefer this over other site-inspection siblings such as check_url, check_domain, or verify_site, so the exclusion set is only partially covered.

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

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

Beyond the read-only annotations, the description discloses important behavioral details: raw counts require the caller to derive rates, filters apply to visits matching all criteria within the same window, full history is the default, and cookieless tracking affects new_visitors/returning_visitors reporting. It also warns that visitors can exceed pageviews because redirect-only hops are included.

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

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

The description is front-loaded with the main purpose and then spends its length on metric definitions and caveats that are necessary to interpret raw counts correctly. Despite being dense, every sentence contributes actionable 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?

With no output schema, the description carries the return-value burden and does so thoroughly by enumerating the KPIs, period comparison, and edge cases such as cookieless tracking and redirect-only visitors. It is complete for an agent to call and interpret the tool correctly.

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

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

Schema coverage is already 80%, so the schema carries most parameter meaning. The description still adds useful semantics by explaining that filters narrow results to visits matching ALL criteria and by clarifying the full-history default when date parameters are omitted.

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 resource and output type: headline KPIs as raw counts for a site, listing visits, visitors, pageviews, clicks, bots, bounces, and durations for current and previous periods. This clearly separates it from detailed breakdown or time-series tools, though it does not explicitly name sibling alternatives.

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 intended use is implied by 'Headline KPIs' and the default to full retained history, but the description never explicitly says when to choose this over get_breakdown, get_timeseries, or get_visitors. It provides interpretation guidance rather than selection guidance.

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=false, so the safety profile is covered. The description adds valuable behavior beyond that: results are in the site's timezone, and omitting the window returns 'the full history the plan retains' — a potentially large default response an agent should know about. No pagination or rate-limit info, but that is a minor gap given annotation coverage.

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 before windowing details. The parenthetical metric list is dense but every element carries information; nothing is redundant.

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

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

No output schema exists, but the description effectively enumerates the returned series (metrics per day) and the timezone. Windowing and full-history defaults are covered; the only missing piece is any hint about response size or pagination for the unbounded full-history case, which matters but is not critical for a read-only reporting 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?

Schema coverage is 60%, and the description fills the most important hole: the undocumented 'days' parameter gets semantics ('Window by days'), as does the interaction with from/to and the default full-history behavior when both are omitted. The nested filters object is left entirely to the schema, which documents it richly, so this is a reasonable balance.

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 ('Daily traffic series for a site') and lists the exact metrics returned (visits, visitors, pageviews, clicks, bots per day) plus timezone semantics. It does not name or differentiate from siblings like get_hourly or get_stats, so an agent must infer the daily-vs-hourly distinction from the word 'Daily' alone.

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

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

The description explains windowing options ('days, or from and to') and the omit-both fallback, which is usage guidance for parameters. It never says when to choose this tool over get_hourly, get_stats, or get_breakdown, so alternative selection is implied only by the word 'Daily'.

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 useful context about the returned visit fields, but it does not explain pagination behavior, default time windows, or limits beyond what the schema partially covers.

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 fragment with no wasted words. It is appropriately concise, though its extreme terseness leaves important usage and behavioral details unstated.

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 7 parameters, nested filters, no output schema, and only minimal annotations, the description is too sparse. It lists returned fields but omits date-range defaults, pagination expectations, filtering behavior, and guidance for a required site parameter.

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

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

Schema description coverage is only 43%, and the description adds no parameter meaning at all. Top-level parameters like site, days, to, and limit are undocumented, while some nested filter fields are described in the schema; the description fails to compensate for the low 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?

The description clearly identifies the resource as recent individual visits and lists the key fields returned: entry page, path, country, device, and human/bot. It is specific enough to distinguish a raw visit log from aggregate tools, though it does not explicitly contrast itself with siblings like get_realtime or get_breakdown.

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

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

There is no guidance on when to use this tool versus alternatives such as get_realtime, get_stats, or get_paths. The word 'recent' is vague and the description provides no inclusion/exclusion criteria or prerequisites.

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

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

Goes well beyond the readOnly/openWorld annotations: it discloses the live-fetch behavior, the 300 KB truncation, the pass/warn/fail result shape, and a prompt-injection warning about untrusted page text. Those are operational facts an agent cannot get from 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?

Purpose and default are front-loaded, and the security warning plus sibling routing land at the end where they belong. The middle is a single semicolon-chained sentence that is dense enough to be harder to scan than a short list, but almost no content is wasted.

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

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

With no output schema, the description still explains the return shape (pass/warn/fail with plain findings), the fetch limit, and every check category. Nothing an agent needs in order to call this 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 already 100%, yet the description still defines what each enum value actually inspects (meta_tags = title/description lengths, robots, viewport, OG/Twitter; canonical = resolution, self-reference, host mismatch, duplicates, hreflang; etc.). That is real meaning beyond the bare enum labels.

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

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

Opens with a concrete verb+resource ('On-page SEO and content checks of ANY public web page'), scopes it to live fetches with a 300 KB limit, and enumerates the exact check categories. It also explicitly distinguishes itself from get_site_health, so an agent can pick it over siblings without opening the schema.

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

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

States the scope (any public page, default check=all) and routes the agent elsewhere for a specific case: 'For an account site's homepage get_site_health already holds the daily SEO and mixed-content audit.' This is explicit when-to-use/when-to-use-something-else guidance.

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, covering the safety profile. The description adds that it returns verification status, which is useful context about the output. However, it does not disclose any additional behavioral traits like sorting, pagination, or potential rate limits. With annotations covering the read-only nature, a score of 3 is appropriate.

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 efficient sentence with no redundant information. It front-loads the action and resource, making it easy to parse. Every word contributes to the tool's purpose.

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

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

Given the zero-parameter schema, no output schema, and overall low complexity, the description is complete. It states what the tool returns (websites with verification status) and needs no further explanation. An agent can call this tool without additional 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 has zero parameters and the schema coverage is 100% (empty). Per the baseline rule for 0 params, the description does not need to compensate for parameter documentation. The description adds value by indicating the output includes verification status, which is relevant to the no-parameter call.

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 action ('List') and the resource ('websites on this DevDome account') with an additional detail ('verification status'). It distinguishes this tool from siblings like add_site or verify_site, which perform different actions. The purpose is unambiguous.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. While it is implied that this is the default listing tool, there is no mention of when not to use it, or any alternative such as get_breakdown or get_stats. The agent must infer usage context from sibling names alone.

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, openWorldHint=false), and the description adds real context beyond them: the catalog scope (AI crawlers, search engines, SEO tools, monitors) and the critical caveat that a user agent can be forged, so a match only reflects what the client claims. It doesn't say how ambiguous or unknown strings are reported, which keeps it from a 5.

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

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

The core question is front-loaded, which is exactly right for a lookup tool, and the catalog/parenthetical detail stays compact. The middle clause listing crawler categories is mildly verbose but earns its place by scoping the catalog.

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, yet the question phrasing implies the return shape (a match plus which bot). Combined with the sibling pointer to get_bot_report, an agent has enough to call it correctly. It stops short of a 5 because it never indicates what a negative or ambiguous result 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 0% with one required parameter, so the description has to carry meaning — and it does: the input is the raw user-agent string being classified, and the forgery caveat signals it should be treated as a claim rather than a verified fact. No format hints (raw header vs. full UA) are given, so slightly short of complete.

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

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

Specific verb and resource framed as a direct question ('Is this user-agent string a known bot or crawler, and which one'), plus the data sources it resolves against (DevDome's bot catalog and the live crawler feed). It explicitly distinguishes itself from get_bot_report, so an agent can tell the two apart 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 clearly routes the agent: use this to classify a UA string, and use get_bot_report to see what actually hit a site. That is an explicit alternative with a selecting condition. It doesn't state exclusions or prerequisites (e.g. that this works for arbitrary UA strings, not just ones in your traffic), so it stops short of a 5.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false, lowering the burden. The description adds meaningful behavioral detail beyond annotations: it discloses that verification works by checking a snippet or DNS TXT record and targets pending sites. No contradictions 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?

One sentence, parenthetical clarification, and zero filler. The verb and resource are front-loaded, and each word contributes 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?

For a one-parameter tool with no output schema and safety annotations present, the description covers purpose, target state, and method. It does not explain what happens on success or failure, but this is minor for a simple verification action.

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 provides 0% description coverage for the single 'domain' parameter, so the description must compensate. It implies domain refers to the pending website's domain, but it does not specify expected format (e.g., with or without protocol) or any constraints beyond 'string'. Partial compensation for a simple one-parameter tool.

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 ('Verify'), a clear resource ('ownership of a pending website'), and the exact mechanism (checks the installed snippet or DNS TXT record). This clearly distinguishes it from sibling tools like add_site and get_stats, which serve 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 implies when to use this tool: for a 'pending website' whose ownership needs confirmation, with the method listed. It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent can decide when verification is the right step.

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