squirrelscan

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

The description discloses behavioral traits beyond the annotations: idempotency per domain, automatic enabling of recurring weekly audits on eligible plans, credit costs, and the presence of scheduled_audits in the result. Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the full burden and does so thoroughly.

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 longer than average but every sentence carries necessary information: core action, idempotency, classification, cost warning, and result field. The most important statement (register without audit, contrast with run_audit) is front-loaded, and the warning is placed logically before usage.

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 2 parameters and no output schema, the description covers all operational aspects: when to use, side effects, return value (website_id and scheduled_audits), idempotent behavior, and cost implications. Nothing an agent needs to call it correctly is missing.

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

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

Although schema coverage is 100%, the description adds meaningful semantics: it explains the effect of 'kind' (owned vs prospect), clarifies that unclassified sites default to 'owned', and notes that re-calling with a different value reclassifies. This goes well beyond the schema's field descriptions.

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

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

The description uses a specific verb ('Register') and resource ('a website with the organization'), and explicitly contrasts itself with run_audit, making its unique role clear. An agent can immediately understand what the tool does and how it differs from the closely related sibling.

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 states exactly when to use this tool ('only needed to set a site up ahead of time'), notes that run_audit registers automatically, and provides a warning to inform the user about costs and how to turn off scheduled audits. This is explicit guidance with alternatives and exclusions.

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

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

The description adds value beyond annotations by mentioning that comments support Markdown and appear in the dashboard issue thread. Annotations already indicate readOnlyHint=false (write operation) and destructiveHint=false, which are consistent. No contradictions.

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

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

The description is two sentences long, front-loads the main purpose, and avoids any wasted words. The Markdown hint is appended efficiently.

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 comment-posting tool with no output schema, the description covers the core functionality, usage context, and a key feature (Markdown). It is complete enough for an agent to select and invoke 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 100%, so baseline is 3. The description adds contextual meaning by stating that the body supports Markdown and that the comment is posted to a thread visible to the team. This aids understanding beyond the schema descriptions.

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

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

The description clearly states the verb 'Post' and the resource 'comment on a website issue'. It further specifies the purpose: to record analysis, proposed fix, or changes, and distinguishes it from sibling tools like delete_website or list_issues by focusing on comment threads.

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

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

The description explicitly says when to use the tool (to record analysis, fix, or changes) and provides context ('so the team sees it in the dashboard issue thread'). It does not explicitly state when not to use it, but the sibling tools list provides implicit differentiation.

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

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

The annotations only indicate read-only, non-destructive behavior, so the description carries the burden of explaining behavior. It thoroughly discloses the seven finding kinds, the meaning of resolutionEvidence, score movement breakdown, and edge cases like first_run and changed: false. This goes well beyond what annotations provide.

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 dense but each sentence adds unique useful information, and the core purpose is front-loaded in the first sentence. The later sentences unpack the seven categories, edge cases, and include flags in a logical order without fluff or redundancy.

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

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

With no output schema, the description compensates by explaining what the response contains: changed findings, seven categories, resolutionEvidence semantics, score movement by category, first_run behavior, changed: false, and default omission of certain rows. This is complete enough for an agent to invoke the tool correctly and interpret its 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: base defaults to the run before head, head defaults to the latest completed run, limit totals are never capped, and the include_* flags correspond to findings that are omitted by default. This enriches the parameter understanding without repeating the schema verbatim.

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 precise verb and object: "Compare two completed audits of one website and get what changed." It clearly distinguishes this tool from siblings like get_audit_status or list_audits by emphasizing comparison and delta reporting rather than status or enumeration.

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 defaults (latest completed audit vs the one before it), how to override with base/head run ids, and behavior for edge cases such as a website with only one audit. It does not explicitly name alternatives or say when not to use the tool, but the usage context is clear and actionable.

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?

Discloses key returned exactly once, scope requirement, and inheritance restriction. This adds significant behavioral context beyond annotations (readOnlyHint=false, destructiveHint=false). No contradiction.

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 clearly structured: purpose, important note, restriction. No wasted words, front-loaded with action.

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?

Adequately explains the one-time return behavior, but lacks explicit output schema or format details for the returned key. Minor gap for a creation 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 100%, but description adds value with examples for name, defaults and list for scopes, and default behavior for expires_in_days. Exceeds baseline of 3.

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 specifies 'Mint a new squirrelscan API key for this organization' with a distinct verb and resource. No sibling tool creates API keys, so it is well-distinguished.

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 context on required scope (keys:write), OAuth, and immediate action (show user, suggest env var). Also notes that minted keys cannot mint keys. Does not explicitly state when not to use, but no alternative exists among siblings.

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 indicate destructiveHint=true, but description adds substantial context: soft delete preserves audits/reports/issues, published links keep working, frees a plan slot, and re-adding creates a new website_id. It also discloses the confirm-step behavior. 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?

Four sentences, each delivers a distinct piece of information: soft-delete semantics, slot effect, re-add behavior, and confirmation workflow plus bulk alternative. No redundant words; front-loaded with the core action.

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

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

The tool's destructive nature is fully contextualized: safety workflow, side effects, and alternative for bulk deletion are all covered. No output schema is needed, and the description provides complete guidance for a complex 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?

Schema coverage is 100% with detailed descriptions for both website_id and confirm. The description reinforces the confirm parameter's purpose through the two-step workflow but does not add meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description opens with 'Delete a website from the organization' – a specific verb and resource with scope. It immediately distinguishes itself from the sibling delete_websites by noting bulk deletion separately. The soft-delete behavior and slot freeing further clarify the exact function.

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 describes the two-call workflow (without confirm, then with confirm) and names the alternative for bulk deletion: 'To remove many sites at once, use delete_websites.' This gives clear when-to-use and when-not-to-use 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?

Beyond the destructiveHint annotation, the description richly discloses behavior: soft-delete semantics, two-step confirm, per-ID error handling, the preview showing owned_count, and the caveat about unclassified sites. This adds significant value and context not available from annotations alone. No contradictions 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?

The description is a single dense paragraph, but every sentence carries important operational or safety information. It is front-loaded with the core action, and while long, the complexity of the tool justifies the length. 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?

For a destructive bulk tool with no output schema, the description covers all critical aspects: what happens on delete, how preview works, how to verify IDs, what errors occur, and how to correctly source IDs. It is fully complete for an agent to safely invoke the 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 100% for both parameters, but the description adds practical semantics: the two-step confirm workflow, that website_ids should come from list_websites, and that duplicates are collapsed. It also warns that every result echoes the domain, reinforcing the importance of confirm. This goes beyond the schema descriptions.

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

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

The description clearly states 'Delete up to 50 websites in one call', which is a specific verb, resource, and scope that distinguishes it from the sibling delete_website. It also provides the use case ('cleaning up a dashboard') and the bulk nature, making the purpose 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 gives clear context on when to use it ('for cleaning up a dashboard filled with one-off or prospect audits') and explicitly points to list_websites as the way to select IDs. It does not explicitly state when to use delete_website instead, but the bulk vs. single distinction is implied through the max 50 limit and the reference to 'same soft delete as delete_website'.

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 only declare readOnlyHint=true and destructiveHint=false; the description carries far more behavioral detail. It discloses the progress field when available, the failure_reason_code enum, failure_next_step, the absence of both on cancelled runs, and the exact relationship of health_score and issues_found to get_report's summary. This goes well beyond the annotations without contradicting them.

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 long but every sentence earns its place: the purpose is front-loaded, then status branches are laid out in reading order, and nuanced edge cases like cancelled vs failed and null health_score are explained with concrete field names. It is dense rather than padded.

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 explaining the response contract. It covers the status states, polling behavior, progress field, error fields, failure reason code enum, next-step guidance, and derived health fields. An agent has enough context to poll correctly, recognize terminal states, and decide whether to call get_report.

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

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

The input schema already covers run_id completely at 100% coverage, including its origin from run_audit or list_audits. The description repeats this origin but adds no new parameter-level semantics such as format, length, or validation constraints, so it stays at the baseline for fully documented schemas.

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 the specific verb and resource: 'Poll a running audit by run_id'. It distinguishes this tool from get_report by explicitly routing completed audits to get_report with the same run_id, and it correctly references run_audit and list_audits as the source of run_id.

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 explicit when-to-use guidance: keep polling every 15-30 seconds while status is pending/running, stop and call get_report when completed, and treat failed/cancelled as terminal states with structured reasons. It also names the provenance of the run_id, so an agent knows which sibling tools feed into this one.

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 destructiveHint=false, and the description does not contradict these. It adds valuable context beyond the annotations, such as the cost per audit, the 50-credit floor, and pricing plans, which help the agent understand the tool's role in the broader ecosystem. It does not describe potential edge cases (e.g., what happens if balance is zero), but for a simple read operation, the added context is sufficient.

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 verbose and includes promotional content, such as detailed subscription prices and a link to upgrade. While some context (audit cost, threshold) is useful, the extended pricing details and call-to-action are not necessary for an agent to call the tool correctly. It would be more effective condensed into two or three sentences focusing on what the tool returns and the credit audit thresholds.

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 read-only tool with no parameters, the description covers the key information: what gets returned (two types of credits), the variable related to audit cost, and the minimum required to run an audit. Though the pricing/upgrade details are extraneous, they do not detract from completeness. The description would be a 5 if the non-essential marketing were removed, but as is, it's a solid, complete description with some noise.

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 schema coverage is 100%. The baseline for a no-argument tool is 4, and since there are no parameters to explain, the description rightly does not add any. It could not add more value here beyond the existing schema.

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

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

The description clearly states what the tool does: it retrieves the organization's credit balance, distinguishing between monthly credits (reset each billing period) and purchased pack credits (never expire). This is a specific verb+resource and easily distinguishes from other tools like list_credit_transactions.

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 context about when knowing the balance is important, noting that audit costs and the 50-credit minimum are relevant before running an audit. However, it does not explicitly mention alternatives like list_credit_transactions, so an agent could be uncertain about when to use this versus transaction history. The guidance is implied 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 destructiveHint=false, indicating safe read operation. The description adds useful context about the returned data (full description, recommendation, affected pages, occurrences from latest report, comment thread), enhancing transparency beyond 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?

Two sentences, zero waste. The first sentence front-loads the purpose and key parameters, and the second sentence provides a cross-reference to a sibling tool. All content 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 read tool with simple parameters and no output schema, the description reasonably covers what the tool returns. It could mention the occurrence_limit parameter or error handling, but the current description is sufficient for an AI agent to understand the tool's capabilities.

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 100% with descriptions for all three parameters (website_id, issue_number, occurrence_limit). The description only mentions website_id and issue_number, adding no extra meaning beyond what the schema provides. The occurrence_limit parameter is not referenced, but its schema description is adequate. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Fetch', the resource 'issue', the identifying keys 'website_id + issue number', and lists the included fields (description, recommendation, affected pages, occurrence detail, comment thread). It also distinguishes itself from the sibling 'comment_on_issue' by directing the user to that tool for adding notes.

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

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

The description explicitly tells the user to use 'comment_on_issue' for adding analysis or fix notes, providing a clear when-not scenario. However, it does not explicitly state when to use this tool versus other siblings like 'list_issues', though the purpose is implied.

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

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

Annotations only declare readOnlyHint and non-destructive behavior, so the description carries the burden of explaining operational nuance. It does so extensively: failure audits carry status keys where null healthScore means crawl failure not a clean site, seedRedirect is display-only and must not be fetched, provenance values distinguish fresh vs carried vs unrendered findings, and the report is the source of truth for run numbers. This far exceeds what annotations alone provide.

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?

Although long, the description front-loads the core purpose in the first sentence and then systematically covers formats, failure modes, provenance, seedRedirect, history, and numeric source-of-truth mappings. Every sentence adds operational value; the length is proportional to the tool's genuine complexity and there is no filler or tautology.

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

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

There is no output schema, so the description must fully describe return semantics, and it does: report formats, healthScore/topIssues structure, provenance and lastSeenAt behavior, seedRedirect edge case, failure status keys, history walking, and the relationship to list_audits and list_issues. An agent has everything needed to correctly invoke the tool and interpret its results across normal and exceptional audit outcomes.

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 100%, but the description adds meaning well beyond the schema by explaining format semantics ('summary' returns structured JSON with health scores and topIssues, 'llm' is compact and marks carried findings inline, 'markdown' is full human-readable), clarifies that run_id comes from run_audit or list_audits, and explains failure-related fields absent from the schema. The top_issue_limit parameter is already fully described by the schema, so the description appropriately focuses where the schema is thin.

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: 'Fetch the finished report for an audit run', and immediately disambiguates from siblings by tying it to run_audit and get_audit_status. It clearly distinguishes the report's role from list_audits, get_audit_status, and list_issues, so an agent knows exactly what this tool is for.

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 explicit when-to-use guidance: wait until get_audit_status shows completed, use the run_id from run_audit, start with summary then escalate to llm/markdown when more detail is needed, and use list_audits with website_id to page past the history array. It also states which values to compare across runs and warns against using list_issues' open count as the report's issue count, providing clear alternatives and exclusions.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds specific return fields and context (e.g., cloud flag, docs link), enhancing transparency beyond annotations without contradiction.

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 concise sentences front-loaded with purpose; every sentence adds essential detail without 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 low complexity (1 param, no output schema, annotations present), description fully covers what the tool returns and why it's useful, including source of rule ids.

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

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

Schema covers the single parameter with description, but description adds examples (e.g., 'meta/title-length') and context on where rule ids appear, providing additional value beyond schema.

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

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

The description clearly states the tool fetches one audit rule by id, listing specific fields like checks, recommendation, severity, score weight, docs link, and cloud flag. It distinguishes from sibling list_rules by specifying single rule retrieval.

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 mentions when to use (fetch a specific rule by id) and where rule ids come from (report topIssues, issue rule_id). Implies not for listing all rules, but does not explicitly state alternatives.

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 flag readOnlyHent=true and destructiveHint=false, and the description adds substantial behavioral detail: active vs recent semantics, total/has_more describing only the recent array, health_score nullability for blocked/down sites, and issues_found sourced from the published report. 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?

The description is dense and front-loaded with the core purpose. It is longer than strictly necessary and includes an internal reference (#1700) that may not be meaningful to all agents, but most sentences earn their place by conveying behavior or routing guidance.

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

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

Even with no output schema, the description explains the meaningful return concepts (active, recent, total, has_more, health_score, issues_found) and their relationships. It also covers pagination, soft-deleted access, and cross-tool usage, making it effectively complete for a listing operation.

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?

Although schema coverage is 100%, the description goes beyond the schema: it explains that website_id works for soft-deleted sites, that limit defaults to 20 and offset to 0, that total/has_more apply only to recent, and that health_score echoes get_report's summary.healthScore. This materially improves parameter understanding.

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

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

The description opens with a clear verb-resource statement: it lists the organization's audit runs (active plus recent of any status). It then distinguishes itself from related operations such as get_audit_status, get_report, and list_issues by explicitly saying where run ids and website ids should be used.

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 explicit when-to-use guidance: pass website_id for full per-site history, use limit/offset for pagination, reach soft-deleted websites’ preserved reports through this tool, and route run ids/website ids to specific sibling tools. It leaves little ambiguity about alternatives.

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 readOnlyHint=true and destructiveHint=false. Description adds behavioral details: each debit/refund carries run_id for grouping, pagination, and explicit 'Read-only' confirmation. No contradictions 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 well-structured, front-loaded with purpose, then details, then usage. While comprehensive, it is efficient and every sentence adds value. Slightly longer than minimal, but not verbose.

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, but description explains return details: newest first, each entry includes run_id, pagination via cursor. Covers what the agent needs to know to interpret results and use effectively.

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 100% with both parameters described (limit with default and max, cursor as opaque pagination token). Description does not add additional semantics beyond schema; baseline 3 is appropriate.

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

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

Description clearly states the tool audits the organization's credit accounting log, listing grants, debits, refunds, adjustments. It distinguishes from get_report (per-feature breakdown) and get_credit_balance (balance), and specifies ordering (newest first, paginated).

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 to explain why an audit cost what it cost or to reconcile a balance.' Also directs to use get_report for per-feature breakdown, clearly differentiating when to use this tool vs sibling.

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 destructiveHint=false, so the safety profile is clear. The description adds valuable behavior: sorting by severity, inclusion of severity/status summaries, per-website tracker spanning audits rather than per-run count, and the persistence model of issues staying open until re-checked. It also explains why counts differ from related tools.

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 longer than average but every section earns its place: it explains the bug-tracker analogy, sorting/summaries, the crucial per-website vs per-run distinction, and routing to siblings. It is front-loaded with the core purpose and saves the numerical caveat for the end. Could tighten slightly, but it's dense and mostly necessary.

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?

Comprehensive for a read-only list tool: it explains return summaries, sorting, filtering, the relationship to get_issue, and the critical caveat about count comparability. No output schema exists, so the description appropriately explains what the response contains and why.

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 100%, so the schema documents all six parameters with descriptions and enums. The description adds context on filtering by status/severity/category and how pagination works through limit/offset defaults, though the schema already covers those details. There's a small bonus for explaining the issue-number link to get_issue.

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 lists a website's open audit issues, compares them to a bug tracker, and specifies each issue is one failing rule with occurrences across pages numbered per website. Distinguishes itself from sibling tools like list_audits, get_issue, and run_audit.

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 guidance on when to use this tool vs alternatives: use issue numbers with get_issue for details, compare runs with health_score from list_audits, and notes that open counts are not comparable to list_audits or report failed/warnings. This is strong alternative-routing.

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?

Discloses ordering (newest first), the data shape (category, title, body, payload ids, read state), filtering options, pagination, and the critical read-only behavior that it never marks anything read. This goes well beyond the annotations (readOnlyHint=true) by detailing what the response contains and how the feed behaves.

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?

Every sentence earns its place: purpose, content, use case, filtering, pagination, and read-only safety. It is front-loaded with the main purpose and remains readable despite covering many details.

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 explaining return values—and it does: category, title, body, data payload, read status. It also covers ordering, filters, pagination, and the use case. Nothing essential is missing for an agent to call this 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 covers 100% of parameters, but the description adds contextual meaning: unread_only is explained as 'what nobody has looked at yet', and pagination via limit/offset is explicitly mentioned. This enriches the schema's baseline without needing to describe syntax.

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 ('Read') and resource ('organization's notification feed'), and immediately tells the agent what it will find: what finished, broke, or changed. It is clearly distinct from siblings like list_audits or list_issues by focusing on notifications and enumerating the exact categories.

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 recommends using this at the start of a session to catch up on scheduled audit results, and contrasts with 'polling every website'. It doesn't name a specific sibling tool as an alternative, but gives enough context to know when to invoke it.

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

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

Annotations already declare readOnlyHint=true. Adds behavioral context about catalog size and grouping. No contradiction. Slight deduction for not detailing pagination or response format.

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 that front-load purpose and grouping, then provide usage guidance and sibling reference. No wasted words.

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?

Provides catalog size, grouping, and filtering context. Lacks description of response fields beyond categories, but sufficient for a list tool given good schema.

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 100%, so baseline is 3. Description adds minimal extra beyond the schema parameter descriptions, essentially paraphrasing filter/search behavior.

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 verb 'browse' and resource 'audit rules' are clear. It distinguishes from sibling 'get_rule' by directing users to that tool for full details.

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 how to filter (by category or keyword) and when to use an alternative ('Use get_rule for one rule's full detail'). Provides context like '260+ rules' and grouping.

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/destructiveHint annotations, the description discloses that unregistered and ephemeral one-shot audits are omitted, that last_report_run_id points to the latest completed report whose report was not deleted, and that the response includes total/has_more for pagination. This adds meaningful behavioral context without contradicting any annotation.

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 dense and front-loaded, with the main purpose in the first sentence. It is longer than average but every clause adds operational detail (ID relationships, exclusions, pagination, filter semantics). A slight trim could improve readability, but no sentence 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 list tool with no output schema, the description covers return fields, pagination, filtering semantics, exclusions, and cross-tool ID usage. It anticipates likely follow-up actions (get_report, list_audits, list_issues) and provides enough context to invoke the tool correctly and interpret results. This is exceptionally 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?

While the schema already covers all three parameters with descriptions, the description enriches the meaning of 'kind' by explaining that unclassified sites count as 'owned' and that 'prospect' only returns explicitly marked sites. It also clarifies pagination semantics (default limit, offset behavior) and the difference between last_run_id and last_report_run_id, adding real value beyond the schema.

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

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

The description opens with a specific verb ('List') and resource ('websites the organization has audited'), and immediately defines the contained fields (latest run status, health score, kind). It distinguishes itself from sibling tools by naming how its IDs relate to get_report, list_audits, list_issues, and by clarifying that unregistered/unused websites are excluded.

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 explicit usage direction: pass last_report_run_id to get_report, use website_id with list_issues/get_issue, and use list_audits for full history. It also states when to use kind=prospect for bulk deletion and that run_audit/add_website are for new registrations, effectively defining when this tool is and isn't appropriate.

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 only signal readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds crucial behavioral context: pay-as-you-go credit spend, the dry-run/confirmation flow, asynchronous execution, auto-registration of the website, and the existence of an auto-run threshold. This goes far beyond annotations and gives the agent a clear model of side effects.

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 dense paragraph, front-loaded with the core purpose and then explaining the confirmation flow, sizing, async behavior, and auto-registration. Every sentence adds value, though it could be broken into bullets for readability. It earns a 4 rather than a 5 due to moderate length.

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 complexity (8 params, async, credits, confirmation, auto-registration), the description covers all key operational aspects: cost, confirmation threshold, polling workflow, max_pages sizing, and auto-registration. It also correctly points to sibling tools for follow-up. The lack of an output schema is offset by pointing to get_audit_status and get_report.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds workflow-level meaning for confirm (dry-run behavior) and max_pages (cheapest run), which helps the agent understand how parameters interact in practice. It does not add detail for every parameter, but the schema already handles those, and the added semantics justify a 4.

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

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

The description clearly states the tool's function: 'Run a cloud audit of a website (crawl + 260+ rule analysis + report).' It uses a specific verb and resource, and distinguishes itself from sibling tools like get_audit_status and get_report by explaining the asynchronous hand-off.

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 guidance on when to use the tool: how to start immediately with confirm: true, how the confirmation_required flow works, when to poll get_audit_status, and when to use max_pages for sizing. It also implies when not to use it (e.g., for checking progress or results) by naming the appropriate 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 show readOnlyHint=false (write) and destructiveHint=false (non-destructive). Description confirms it is for feedback submission, reviewed by team, and works with any credentials. No contradictions or missing behavioral details.

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 three sentences long, front-loaded with action and purpose. Every sentence adds value without redundancy.

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

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

For a feedback submission tool with no output schema, the description fully explains its purpose, usage timing, and compatibility. All parameters are well-documented in the schema. No 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 100%, so baseline is 3. The description itself does not repeat parameter details but provides overall context. No additional semantic value beyond the schema is added by the description text.

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

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

The description uses specific verbs ('report your experience') and resource ('squirrelscan mid-session'), clearly distinguishing it from sibling tools (no other feedback tool exists).

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 ('any time something surprises you, not just at the end of a session'). Does not explicitly mention when not to use, but alternatives are not needed since no feedback sibling exists.

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 destructiveHint=false. The description adds specific behavioral context about what information is returned (credentials, organization, plan, credit balance), which is useful beyond the annotations.

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

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

The description is two sentences long, front-loads the action ('Identify'), and provides all necessary information without unnecessary words.

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 (no parameters, no output schema), the description adequately explains the tool's purpose and return value. It is complete for an identity/authentication tool.

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

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

The tool has no parameters, so the description does not need to add parameter meaning. With schema description coverage at 100% (empty schema), a baseline score of 4 is appropriate.

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

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

The description clearly states 'Identify the current credentials: how you are authenticated, which organization you act for, the plan, and the current credit balance.' It uses a specific verb and resource, and the nature of checking credentials distinguishes it from sibling tools like list_websites or get_issue.

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

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

The description explicitly says 'Call this first in a session to orient yourself before running audits,' providing clear context for when to use it. However, it does not mention when not to use it or alternatives, so it falls short of a perfect 5.

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