SiteGuardian

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful context: returns domain_not_monitored error for unmonitored domains, excludes compliance framework tags in v1, and requires a valid API key. No contradiction with 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?

Description is slightly longer than necessary but every sentence adds value: return contents, use cases, error scenario, and version limitation. The most important information is front-loaded in the first sentence, with exclusions following. No 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?

Given the tool's simplicity (one parameter, output schema present) and strong annotations, the description covers essential operational context: when to use, when not to use, error behavior, API key requirement, and version limitations. It is fully complete for an agent to select and invoke 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?

The schema provides only a 'domain' string with no description (0% coverage). The description compensates by explaining the domain must be 'ALREADY under SiteGuardian monitoring by the authenticated account', which gives the parameter practical meaning beyond a bare string. It does not specify format details but is sufficient for a single parameter.

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 returns security grade, last-scan timestamp, active issues, and a dashboard URL for a monitored domain. It distinguishes itself from siblings like list_monitored_domains and scan_domain by specifying 'specific monitored domain' and explicitly naming 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?

Explicit usage guidance: 'Use this when the user asks about the current state of a specific monitored domain, wants to confirm a recent change landed, or needs issue ids'. It also provides a clear exclusion with a specific error behavior and directs users to scan_domain for unmonitored domains.

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 annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds practical behavior: the domain_not_monitored error, ISO-8601 and limit range constraints, and the API key requirement. It also explains severity classification logic and the sanitized detail payload, which are not available from annotations.

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

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

The description is front-loaded with purpose, then usage, then caveats, and avoids unrelated details. It is slightly long but each sentence carries useful information; the only minor issue is a likely typo repeating 'get_drift_events' where get_domain_status was intended, but overall structure is clean.

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?

Even though an output schema exists, the description independently details event fields, severity levels, error behavior, parameter constraints, and authentication requirements. It is complete enough for an agent to decide when to invoke this tool and what to expect, without needing to inspect other documentation.

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 compensate. It explains 'since (ISO-8601)' and 'limit (1..100)' for the optional parameters, and 'domain' is self-evident from the tool name and opening sentence. It doesn't provide exhaustive per-parameter schema details but covers the key constraints and formats.

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 'Returns recent configuration drift events for a domain under monitoring by the authenticated account' and enumerates concrete types (TLS changes, DNSSEC, security headers, JS hosts, cookies), giving a specific verb+resource+scope. It explicitly distinguishes itself from the sibling tool get_domain_status by positioning itself as the history counterpart to the current-state 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 description states 'Use this when the user asks "what changed" on a domain, wants to audit recent posture shifts, or is diagnosing an unexpected issue' and pairs it with get_domain_status for current state. It also provides a 'Do NOT use' warning for unmonitored domains with the resulting domain_not_monitored error, covering both affirmative and negative usage conditions.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds critical behavioral context: it NEVER triggers a fresh scan and always computes from the most recent stored scan. It also mentions the API key requirement, adding value beyond structured annotations.

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

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

The description is somewhat long but well-structured: it leads with the core value proposition, then details usage, exclusions, and behavior. Each sentence carries useful information, and the length is appropriate for the tool's complexity.

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 description covers eligibility (paid coverage), usage context, exclusions, behavioral guarantees, and alternatives. With an output schema present, the lack of return-value detail is acceptable. It is complete for effective tool selection and invocation.

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

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

Schema description coverage is 0%, but the description compensates by explaining domain as the target and issue_id as an optional scoping parameter. It clarifies that issue_id scopes to a specific finding, which is meaningful. However, it doesn't specify domain format or constraints, leaving some gaps.

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 it returns copy-paste-ready fix recommendations for specific issue types (nginx, Apache, DNS, shell) on a paid-for domain. This distinguishes it from siblings like scan_domain, which triggers scans, and get_domain_status, which reports status.

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

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

Explicitly states when to use (user asks how to fix an issue, wants config to apply, or needs to verify a fix) and when not to (unpaid domains, triggering scans). It names scan_domain as the alternative for anonymous checks, providing clear decision criteria.

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 indicate read-only/idempotent, but the description adds valuable context: API-key scoping, no filter parameter, and that it does not trigger scans. Also notes the auth requirement and return contents, going beyond the annotations.

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

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

Three short, focused paragraphs: function, when-to-use, and exclusions. Every sentence serves a purpose with 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?

Given no parameters and an output schema, the description still explains the return fields, scope boundaries, and sibling-tool relationships. Offers complete guidance for correct invocation and interpretation.

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 zero parameters, the input schema is trivially covered. The description explicitly confirms there is no filter parameter, preventing the agent from imagining optional inputs. This adds meaningful semantic clarification beyond the empty 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?

Clearly states it returns the full list of monitored domains for the authenticated account, with specific fields. Distinguishes itself from sibling tools by positioning them as separate actions (get_status, get_drift_events, etc.).

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 provides when to use (inventory summary, exact spelling lookup) and when not to use (other people's domains, triggering scans), naming scan_domain as the alternative. Perfectly clear selection criteria.

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 read-only, open-world, idempotent, and non-destructive hints. The description adds meaningful behavior beyond these: two-hour caching with cached=True flag, per-source-IP and per-target rate limits, and no authentication required. These are non-obvious traits that help the agent anticipate results and limitations.

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, each earning its place: action/results, when-to-use, caching behavior, explicit exclusions with alternatives. The most critical information is front-loaded, and no fluff or repetition exists. Despite being longer than two sentences, it is appropriately sized for the behavioral nuances it conveys.

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 simple signature (one parameter), the description is complete: purpose, outputs, use cases, exclusions, alternative, caching, rate limits, auth requirement, and the output schema exists for return details. Sibling tool names in context also help disambiguation. Nothing critical 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?

The schema has only one string parameter 'domain' with 0% description coverage. The description adds context by referring to 'the given domain' and clarifying it should be a non-monitored domain in the usage section. It doesn't specify format constraints (e.g., with/without scheme), but for a single obvious parameter, this is adequate and above baseline.

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 specific verb and resource: 'Runs a free one-off security scan of the given domain' and lists exact outputs (grade, timestamp, top issues, permalink). It also differentiates from siblings by explicitly noting when to use this versus get_domain_status, making the purpose unmistakable.

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 ('NOT yet under SiteGuardian monitoring', 'fresh assessment before subscribing') and when-not-to-use ('already under monitoring', 'batch-scan as competitive-intelligence tool'), naming the alternative tool get_domain_status. This is textbook-grade usage guidance.

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