squirrelscan

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

Discloses key behaviors beyond the annotations: idempotent re-calls return the existing website, re-passing kind or scope replaces stored values, a new site's recurring audits switch on after the first successful audit, and each run costs credits. It even instructs the agent to warn the user before calling, which annotations (readOnly=false, destructive=true, openWorld=false) cannot convey.

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 purpose and the run_audit distinction are front-loaded, and the sentences are information-dense. It is longer than typical, though almost every clause carries operational weight; the closing line about the scheduled_audits field is the most expendable.

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 reports the return value (website_id) and the relevant result field (scheduled_audits). Combined with the credit-cost warning, idempotency note, and sibling routing, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the enum parameters already carry detailed descriptions, so the baseline applies. The description reinforces the replacement-on-re-call semantics and the meaning of kind, but adds little syntax or format detail beyond what the schema already states.

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: 'Register a website with the organization without running an audit', and immediately distinguishes it from run_audit, which registers automatically. An agent can tell exactly what this does and how it differs from the primary 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?

Explicitly says this is only needed to set a site up ahead of time, since run_audit registers automatically. It also names update_website_settings with schedule 'off' as the way to turn off recurring audits, and tells the agent to pass kind up front. When-to-use, when-not, and the alternative are all 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 this is a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds useful context beyond that: the comment is surfaced to the team in the dashboard issue thread and markdown is supported. It stays silent on return values, editability/deletion of comments, and error behavior, so it adds moderate value rather than rich behavioral detail.

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 for purpose and audience plus a four-word note on formatting; zero filler and the action is front-loaded.

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 three-parameter write with full schema coverage and safety annotations, the description covers what is being created and who sees it. Given no output schema exists, a brief note on the response or failure modes (e.g. invalid issue number) would make it fully 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?

Schema description coverage is 100% and all three parameters are documented, including that issue_number comes from list_issues and that body is markdown. The description only restates the markdown support already in the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Post a comment on a website issue') and then enumerates the concrete purposes (analysis, proposed fix, changelog note), which makes it unmistakable next to read-oriented siblings like get_issue and list_issues.

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 states when to use the tool ('to record analysis, a proposed fix, or what you changed'), giving an agent good context for intent. It does not, however, rule out alternatives or mention prerequisites such as needing an existing issue, so it stops short of explicit when-not 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 establish read-only and non-destructive behavior, and the description adds substantial contextual detail: the eight finding kinds, how sampled-out findings are treated, what resolutionEvidence means, when first_run or changed:false is returned, and that omitted row types do not affect totals. This is rich behavioral disclosure beyond structured fields.

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 purpose and defaults are front-loaded, and almost every sentence carries useful semantics about finding kinds or edge cases. The single dense paragraph is long and includes a complex parenthetical taxonomy, which slightly reduces readability but does not waste much space.

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

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

The tool has eight parameters, no output schema, and only simple read-only annotations; the description compensates by explaining return-state semantics, classification kinds, omission behavior, and totals. It is complete enough for an agent to call and interpret the comparison 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 description coverage is 100%, so the schema already defines every parameter. The description still adds value by explaining that base/head default to consecutive completed runs, that include_* flags control omission of unchanged, still-open, not-crawled, and not-checked rows, and that totals count every kind even when rows 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 opens with a specific verb and resource: 'Compare two completed audits of one website and get what changed.' It also states the default comparison pair (latest completed audit vs. the one before it), so an agent can distinguish this from siblings like list_audits or get_report 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 clearly explains when the default applies and how to override it with base/head run ids. It does not explicitly name alternative tools such as compare_entities or get_report and say when not to use this one, so usage guidance is clear but lacks sibling 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 establish a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description goes well beyond them: it explains the conservative removal rule ('only reported as removed when every page that declared it was crawled again'), the meaning of the coverage field ('proven' vs 'partial'), and the key-change pitfall where an @id fix appears as a removal plus an addition.

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 change-set contents and mostly dense with real behavioral information, but the coverage field is explained twice (mid-paragraph and again in the closing sentence about 'proven'/'partial'), which is avoidable repetition.

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

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

With no output schema, the description carries the full burden of explaining the return shape, and it does: change-set sections, coverage semantics, direction fields, and the occurrenceDeltas scope. For a 4-parameter diff tool this leaves nothing an agent needs 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 100% and the schema itself already documents defaults, ordering, website_id precedence, and the occurrence_threshold noise guidance, so the description adds little new semantics for the parameters. Baseline 3 is appropriate where the schema does the heavy lifting.

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 precise verb and resource ('Compare two audits of a site and get the change set') and then enumerates the exact entity-level outputs it produces (added/removed entities, gainedId/lostId, occurrence deltas, conflicts, dangling refs, page coverage). That entity-level granularity makes it unmistakable from the sibling compare_audits, which works at audit level, so an agent can route 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?

Gives an explicit when-to-use workflow: call list_entities with problem="no-id", assign absolute @ids, re-run with run_audit, then call compare_entities and verify gainedId. It also names the default direction (previous vs latest) and warns where gainedId absence is not proof of failure, so both the trigger and the non-trigger are 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?

Goes well beyond the annotations by disclosing that the returned secret is a live credential shown exactly once and never retrievable again, and that it must be persisted immediately — critical behavior for a destructive-flagged mutation. It also names the required authorization scope and who holds it.

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 front-loaded sentences with the action first and the one-time-secret warning immediately after. Slightly dense phrasing ('a secret, a live credential for the organization') but no filler sentences.

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 correctly explains the return (a secret shown once), plus auth and irreversibility. It leaves the default scopes and expiry to the schema, which already covers them, so nothing essential for correct invocation 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 description coverage is 100%, with name, scopes (including defaults and grantable values), and expires_in_days fully documented in the schema. The description adds no parameter detail, which is acceptable at this coverage level but earns only the 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?

States a specific verb and resource ('Mint a new squirrelscan API key for this organization and return it') and its scope. No sibling tool competes with key creation, so an agent can select it unambiguously.

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 the intended downstream use (save as SQUIRRELSCAN_API_KEY for CLI, CI, MCP) and the prerequisite scope (keys:write, granted to owner/admin via OAuth). It also states an exclusion-like constraint: minted keys cannot mint keys. No sibling alternatives exist to route against, which is the only missing piece for 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 declare destructiveHint=true, but the description adds critical context beyond that: it's a soft delete that preserves audits/reports/issues, published links keep working, it frees a plan slot, and re-adding the domain yields a new website_id. This is exactly the kind of consequence detail annotations cannot convey.

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-loads the deletion and soft-delete consequence, then the plan-slot and re-registration notes, then the confirm flow, then the sibling. Every sentence carries distinct, useful information with no waste.

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?

Covers what the operation does, its reversibility/preservation behavior, side effects on plan limits, identity change on re-add, the confirmation protocol, and the bulk alternative. Nothing an agent needs to invoke it safely 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 100% and the schema already documents both website_id and confirm with the confirmation flow. The description reinforces the two-step confirm pattern but adds no additional parameter detail 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?

States a specific verb+resource ('Delete a website from the organization') and immediately clarifies soft-delete semantics, distinguishing it from the sibling delete_websites which is named for bulk removal.

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 tells the agent to call once without confirm to preview, then again with confirm: true to delete, and routes bulk removal to delete_websites. When-to-use and alternatives are both named.

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 declare destructiveHint=true, and the description adds substantial context beyond that: it is a soft delete (audits, reports, issues preserved; report links keep working; slots freed), errors are reported per-id rather than as whole-call failures, and the preview exposes kind plus an owned_count that misreads unclassified sites as owned. This is exactly the non-obvious operational detail annotations cannot carry.

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 verb, scope, and purpose, then flows into behavior. It is long, but the density is justified by the destructive bulk operation; only the repeated emphasis on reading domains back borders on 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?

No output schema exists, yet the description covers return behavior (every result echoes the domain, per-id error reporting), destructive side effects, the confirm workflow, and id-selection guidance. An agent has everything needed to invoke this safely.

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 schema already documents confirm and website_ids. The description still adds value by framing confirm as a preview/approve loop and by explaining what the preview actually surfaces (domain per id, kind, owned_count), which shapes how the parameter is used.

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 with scope ('Delete up to 50 websites in one call') and the intended scenario (cleaning up a dashboard of one-off/prospect audits). It is clearly distinguished from the single-site sibling delete_website, which it explicitly references.

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 explicit when-to-use context (bulk cleanup), the exact workflow ('call once without confirm... then again with confirm: true'), and names the alternative for id selection ('list_websites with kind: "prospect"'). It also instructs the agent to read domains back to the user before and after, with a stated reason.

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 covered. The description still adds substantial behavioral context beyond them (queue position/ETA semantics, terminal status meanings, recurring-audit side effects and credit charges), but the score reflects that much of the value here is return-value semantics rather than traits the annotations couldn't already convey.

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 polling loop, but the body sprawls into an extremely long block covering failure codes, diagnostics attribution, health_score provenance, and scheduling economics. Much of it earns its place, yet the density and run-on sentences hurt scannability for an agent.

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 the response surface — status values, progress fields, failure_reason_code enum, failure_diagnostics, health_score, schedule and estimated_cost — and it does so thoroughly.

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 the single run_id parameter and the schema already documents it. The description only restates its origin (run_audit or list_audits), matching the baseline for a fully documented 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?

States a specific verb and resource (poll a running audit by run_id) and immediately anchors run_id's origin to run_audit/list_audits, distinguishing it from the sibling that starts a run and the sibling that fetches the report.

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 polling cadence (every 15-30 seconds), explicit 'do not start the audit again', and explicit routing to get_report on completion. Status-specific next steps are spelled out rather than inferred.

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 readOnlyHint annotation by disclosing the credit lifecycle (monthly resets, pack credits never expire), the pay-as-you-go spend model, the exact audit cost formula, and the failure threshold (under 52 credits cannot start an audit). 'Read-only' restates the annotation but nothing contradicts it.

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-loads what the tool returns before covering spend mechanics and thresholds, and every sentence carries decision-relevant information. The detailed cost formula is arguably closer to run_audit's domain, making the paragraph slightly heavier than a pure balance getter needs, but it is dense rather than 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 carries the burden of describing return values and does so by naming the two credit categories. Combined with the spend/threshold context, an agent has everything needed to interpret and act on the result.

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 takes zero parameters, so per the rubric the baseline is 4; there is no per-parameter semantics to document and the description correctly adds none.

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 ('Get the organization's credit balance') and immediately decomposes the resource into its two distinct kinds (monthly credits vs. pack credits), which also separates it conceptually from the sibling list_credit_transactions that reports history rather than current state.

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 clear context tying the balance to audit spending and explicitly points at run_audit as the tool that shows an upper-bound estimate before starting. It stops short of an explicit 'call this when/do not call this when' statement, so no exclusions are given, but the decision context is well established.

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 cover the read-only/non-destructive profile, but the description adds substantial undisclosed behavior: the map stores only nine properties plus @type, disagreements outside that set are undetected, edges and declaring pages are capped with counts signalling truncation, and the coverage field distinguishes "proven" from "partial". These are real limitations an agent could not infer from the schema or 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 what-it-returns content is correctly front-loaded, but the long fix-and-verify narrative about gainedId, compare_entities, and re-running audits is multi-tool workflow material that belongs with those tools, not in a getter's definition. It inflates the description well past what is needed to invoke get_entity.

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 and delivers: it lists the returned fields, the disagreement detection scope, the truncation behavior and how counts reveal it, and the key-resolution fallback. An agent has everything needed to call and interpret the result 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% and the key resolution order, run_id defaulting/pass-over behavior, and website_id precedence are already fully documented in the schema field descriptions. The description only restates 'Accepts the entity key, its @id, or its name,' adding no syntax or format 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 and then enumerates the exact payload: the nine properties the map keeps, declaring pages, value disagreements, and inbound/outbound references. This clearly separates it from siblings like list_entities (enumeration), get_entity_graph (topology), and compare_entities (run-to-run diff).

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 places the tool in a workflow: 'Use this after list_entities to see why an entity was flagged, before deciding what to change,' and names the alternatives (list_entities with problem="no-id", run_audit, compare_entities) with the condition that selects each. Nothing about when-to-use is left to inference.

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 read-only safety, yet the description adds unusually rich behavior: findings aggregate one problem site-wide (so count 1 can mean hundreds of pages), the keys/pages lists are a SAMPLE clipped before this tool saw them with no total reported, and 'analyzed: false' means empty findings are absence of evidence, not a clean result. These are non-obvious interpretation rules an agent cannot get 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?

Front-loaded with purpose and then dense with non-obvious semantics, so most sentences earn their place. However, the extended fix-and-verify loop spans several sibling tools and pushes length well beyond what is strictly needed to select and invoke this tool.

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 no output schema, the description fully covers the return semantics (findings structure, sample/clipping caveat, analyzed flag, coverage field values 'proven'/'partial') plus how to confirm a fix landed via gainedId. Nothing an agent needs to interpret the results 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 description coverage is 100% and both parameters are thoroughly documented in the schema itself (run_id defaulting behavior, website_id being ignored by the local server, run_id precedence). The description adds workflow context around run_id but no new syntax or format detail, so the schema carries the load — baseline 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?

States a specific verb and resource ('Get the schema/entity-* rule verdicts for an audit') and enumerates exactly what each finding contains: the problem, the affected keys/pages, and the fix text. It explicitly distinguishes this from re-deriving problems from the graph and points to list_entities as the sibling for the full set.

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 explicit routing: 'Use this instead of re-deriving the problems from the graph yourself' and 'Use list_entities with the matching problem filter for the full set.' It also lays out the full fix-and-verify loop (list_entities, run_audit, compare_entities) with the exact condition that selects each step.

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?

Far exceeds the readOnly/openWorld annotations: it discloses per-format node caps (mermaid 150, markdown 50) and that truncation is announced, that empty arrays mean 'never stored' rather than 'nothing matched', that a server may refuse an unsupported format rather than return partial data, and that mermaid's cap bounds declared entities only. These are exactly the quirks an agent needs to interpret output correctly.

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 format tradeoffs are front-loaded and each sentence carries substantive information with little filler. It is long, and the closing fix-and-verify loop drifts into a multi-tool workflow (list_entities, run_audit, compare_entities, gainedId) that is only loosely tied to this tool's own call.

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 well for edge cases: truncation messaging, empty-array causes, refusal behavior, and coverage-field semantics. It stops short of describing the actual shape of the canonical json/jsonld document, which is the one remaining gap for an 8-parameter export 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% and the parameter descriptions are already rich, so the baseline is 3. The description adds meaning beyond the schema for the format parameter by attaching behavior to each value (which formats cap and which do not) and clarifies run_id selection in workflow terms, which is a genuine increment.

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 specific verb and resource: 'Get the whole entity graph, or a filtered part of it, in a chosen format', then enumerates the concrete output formats. It ties itself to siblings by noting it 'Takes the same filters as list_entities', letting an agent distinguish the bulk-export tool from the list tool 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?

Gives clear context for choosing a format ('mermaid or markdown to read in a conversation, dot or graphml for a graph tool') and for naming run_id ('If you are checking whether a change landed, name the run'). It does not explicitly state when to prefer this tool over list_entities or get_entity, so the when-not guidance is implied rather than spelled out.

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

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

With annotations already covering the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), the description adds substantial data-semantics context: occurrence_count is the true total, listed occurrences are a sample when occurrences_truncated is true, and full_detail reveals where every occurrence lives on a capped report. That is exactly the non-obvious behavior the agent needs for a read and is not derivable 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?

Front-loaded with identity ('Fetch one issue by website_id + issue number'), then the returned payload, then the truncation caveat, then the cross-tool cue. Two dense sentences with heavy parentheticals; every clause earns its place, though the parenthetical stacking makes it slightly harder 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?

There is no output schema, so the description correctly carries the burden of describing return values (full description, recommendation, affected pages, occurrence detail with snippets, comment thread). Combined with the truncation caveats and the comment_on_issue handoff, an agent has everything needed to call and interpret this 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 description coverage is 100%, so baseline is 3 and the schema already documents website_id, issue_number, and occurrence_limit. The description goes beyond by explaining the consequence of the occurrence limit (truncation and sampling flagged by occurrences_truncated, pointer to full_detail), which the schema only gestures at with 'see occurrence_count/truncated'.

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 ('Fetch one issue') and the exact key (website_id + issue number), distinguishing it cleanly from the browsing sibling list_issues. It also enumerates the payload an agent gets back (description, recommendation, affected pages, occurrences, comments), so the tool's scope is unambiguous 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?

Usage context is clear: this is the detail fetch for a single issue identified from list_issues. It also routes the agent to comment_on_issue for adding analysis or a fix note. It does not explicitly state when to prefer this over list_issues or other siblings (e.g. get_report for report-level data), so the routing is implied rather than exhaustive.

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 cover read-only safety; the description adds substantial behavioral detail beyond them - capped reports keep a sample beside true counts, published reports carry `detail.note`, the history array is limited to 3 prior audits, and failure audits carry four extra keys. It slightly over-specifies return payloads (which with no output schema is warranted) but never contradicts the readOnly/non-destructive hints.

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 purpose and precondition are front-loaded, but the remainder is one dense ~700-word run-on block with no line breaks or bullets, and the closing source-of-truth paragraph repeats points made earlier. The content mostly earns its place, but the wall-of-text format makes it hard for an agent to scan for the key 'do not trust empty topIssues' warning.

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 complex nested payloads (provenance, notChecked, seedRedirect, structure, failure keys), the description carries the full documentation burden and does so thoroughly, including the pitfall that list lengths are samples rather than totals. Nothing an agent needs in order to interpret or re-call the tool 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 100% and every parameter is documented there, so the baseline is 3; the description earns an extra point by explaining the trade-off between the three `format` values and the exact lineage of `run_id` (run_audit / list_audits). `top_issue_limit` is left to the schema, which fully covers it.

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 specific verb+resource ('Fetch the finished report for an audit run') plus the exact precondition (run_id from run_audit, once get_audit_status shows completed). That single clause cleanly distinguishes it from get_audit_status and list_audits, which an agent could otherwise confuse it with.

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 explicit sequencing ('Start with summary, then pull llm or markdown'), tells the agent to re-call get_report with an earlier runId to walk history or use list_audits to page past it, and to use get_issue for individual occurrences. It also states when not to trust a result ('never report those rules as clean', null healthScore means the crawl failed, NOT that the site is clean).

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description adds real behavioral detail by enumerating the returned attributes, notably the 'cloud (credit-billed) rule' flag which has cost implications.

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 dense sentence, but it is front-loaded with the core action and the trailing clause earns its space by listing return fields; slightly long but 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?

There is no output schema, and the description compensates fully by enumerating what the response contains (checks, fix recommendation, severity, score weight, docs link, cloud flag), which is everything an agent needs to call and interpret it.

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% and the single rule_id param is already documented as 'category/slug', so the schema carries the load; the description's example ('core/meta-title') reinforces the format but adds little beyond the schema. 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 ('Fetch one audit rule by id') with an example id, and the singular 'one ... rule' cleanly distinguishes it from the sibling list_rules.

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?

Tells the agent where rule ids come from (report topIssues and issue rule_id fields), which is genuine routing context, but never explicitly contrasts with list_rules or states when-not to use this tool.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds substantive behavioral nuance: plan-limited runs_as behavior, credits_per_run_max cost caps, pending_first_audit activation after a successful audit, and recurring schedule/cost semantics.

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 purpose is front-loaded, but the remainder is a long, dense enumeration in a single paragraph. Much of the detail earns its place because there is no output schema, but the structure is burdensome and could be clearer with field grouping or bullets.

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 burden of explaining returned data and does so thoroughly: audit level, crawl settings, ownership, broken-link alerts, plan-limited runs_as, credit caps, and recurring-audit activation/cost semantics. It is complete enough for an agent to understand what this read tool returns and how plan constraints affect the values.

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?

There is only one parameter, website_id, and schema description coverage is 100%, with the schema already explaining it comes from list_websites, run_audit, or add_website. The description adds no additional parameter-level meaning, so the high-coverage baseline of 3 applies.

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

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

States a specific verb, 'Read', and a specific resource, 'one website's stored audit settings', then enumerates the settings returned. It does not explicitly distinguish itself from update_website_settings or list_websites, so it is clear but lacks full sibling differentiation.

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 explicit when-to-use or when-not-to-use guidance, and the description does not route the agent between this tool, update_website_settings, or list_websites. 'Read one website's stored audit settings' implies inspection, but the usage context is left to inference.

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 a safe, non-destructive read, but the description adds behavior the annotations cannot convey: queued runs wait for a free cloud slot and start by themselves, total/has_more cover only the `recent` array, and preserved runs of soft-deleted websites remain reachable by their old website_id. This is substantial lifecycle and edge-case context.

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 purpose is front-loaded and most clauses carry weight, but the paragraph is a dense run-on that restates the recent-vs-active relationship twice (total/has_more describe recent only, and recent already includes active) and buries the metric semantics in a long final sentence. It is more verbose than it needs to be for a three-parameter list tool.

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 carry the return semantics, and it does: it defines the active/recent arrays, total/has_more, the source of health_score (#1700 report's overall score, null when blocked or down), and how issues_found is derived. An agent has everything needed to call and interpret it.

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 three parameters are already documented, setting a baseline of 3. The description adds real meaning on top: it ties website_id to list_websites as the source, notes it works for soft-deleted sites, and defines the limit/offset pagination contract in terms of the returned total/has_more.

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 (list the organization's audit runs) and immediately scopes it to active plus recent runs. It clearly distinguishes itself from siblings by naming get_audit_status, get_report, and list_issues as the tools for the downstream artifacts this list points at.

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 explicit when-to-use conditions: pass website_id for one site's full history, use limit/offset with total/has_more to page, use run ids with get_audit_status/get_report and website ids with list_issues. It also flags the soft-deleted-website case and an explicit 'do NOT compare issues_found with the open count from list_issues', which is a genuine anti-pattern warning.

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

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

The description discloses ordering (newest first), pagination behavior, the grouping key run_id, and that it is read-only. Annotations already declare readOnly/destructive hints. It doesn't detail rate limits or result shape, but adds substantial useful context 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?

The description is structured and mostly front-loaded with the purpose, then usage context. It is fairly dense and long but every clause is informative. Slightly over-packed with cost-detail examples, but no real waste.

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 output schema and simple pagination parameters, the description is complete enough for an agent to invoke it correctly, covering what data it returns, ordering, grouping, and when not to use it. It could say more about the response item shape, but the key behavioral contract is present.

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 already documents limit and cursor semantics. The description mentions pagination and 'newest first' but does not add syntax or constraints beyond what the schema provides, so the 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 states a specific verb and resource: auditing the organization's credit accounting log, listing grants, debits, refunds, and adjustments. It distinguishes itself from the sibling get_report by explicitly naming the per-audit breakdown alternative.

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 gives clear when-to-use cases (explain audit cost, reconcile a balance) and explicitly names the alternative (get_report's cost field) for per-feature breakdowns, so an agent knows when to choose this tool versus another.

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 a safe read, and the description adds substantial behaviour beyond them: default hiding of page-local entities, the run_id default that skips entity-less audits, stable paging order, the split-identity failure mode, the gainedId-only confirmation of a fix, and the proven/partial meaning of coverage. This is exactly the kind of context structured fields cannot carry.

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 purpose and folding rule, and every later sentence carries operational information. It is dense and runs long, with some rhetorical padding ('not a quirk of this tool') and a long fix-and-verify block, but little is genuinely 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 carries the return shape itself, enumerating the unfiltered site-wide summary, the filtered node/edge counts, the page of nodes, total and hasMore. For a 9-parameter, zero-required list tool with rich paging and audit-run semantics, 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?

Schema description coverage is 100%, so the baseline is 3, but the description still adds value: it summarises the filter axes (@type, declaring page, problem class, name text match), justifies the include_page_local default, and explains that hasMore governs continued paging. It stops short of restating the prefix-vs-substring matching rules, which the schema already handles.

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 and scope: 'List the entities a site declares in its JSON-LD, collapsed across every crawled page into one graph.' The collapsing rule (by resolved @id, else by type+name) and the split-identity caveat make the tool's identity unmistakable and distinct from get_entity, get_entity_graph and compare_entities, which it also names in the workflow.

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?

Clear context is given: use problem filters for the fix-and-verify loop, keep paging while hasMore, hide page-local entities unless include_page_local, and name run_id when verifying a change. It routes to compare_entities and run_audit as follow-up steps, but never states an explicit exclusion or contrast against get_entity/get_entity_findings, so it stops short of full when-not coverage.

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 cover the read-only safety profile, and the description adds substantial behavior beyond them: severity sorting, the semantics of total/returned/has_more versus website_totals, the caveat that website_totals ignores filters, and that the long recommendation is omitted by default. The issue-lifecycle explanation (one issue per failing rule, stays open until re-checked) is genuinely useful operational context.

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 is front-loaded and most sentences carry non-obvious information (totals semantics, comparability warning). It is dense and long, and the parenthetical noting it 'replaces the earlier severity_summary and status_counts fields' is API-internal detail that does not help an agent decide or call correctly.

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 complex, paginated, filterable tracker with no output schema, the description explains the returned counters, the default field omission, and the counting semantics well enough that an agent understands the response shape and the filters without further 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning on top: include_recommendation's default-omission behavior and its relationship to get_rule/get_issue, plus the purpose of status/severity/category filters for narrowing. It does not add syntax the schema lacks for limit/offset.

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 ('List a website's open audit issues') and immediately clarifies the data model ('each issue is one failing rule with occurrences across pages, numbered per website'). It explicitly distinguishes itself from sibling list_audits and per-run counts, so an agent can route correctly 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?

Names concrete alternatives and the conditions selecting them: use get_rule / get_issue for the recommendation, get_issue for full detail and comments, list_audits' health_score to compare runs. It also warns that this per-website count is not comparable to a run's issues_found, an explicit when-not.

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/destructiveHint, but the description adds a genuinely non-obvious trait: reading 'never marks anything read'. It also discloses ordering flip under `after` (oldest first) and that offset is ignored in that mode. Return-shape details (payload ids, read state, next_cursor) shade into completeness rather than 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?

Dense but front-loaded: what it is, then why/when, then entry shape, then filters, then pagination. Every sentence carries information, though the enumeration of categories and the parenthetical example questions push it slightly past minimal.

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 covers what an agent needs: entry contents (category, title, body, payload ids, read state), pagination contract, and next_cursor round-trip for polling. Nothing material is left to guess for a zero-required-param 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 100%, so the baseline is 3, but the description adds meaning the schema doesn't: the interaction between `after` and `offset` ('offset is ignored'), that `after` reverses ordering to oldest-first, and how `category`/`unread_only` combine. That is real added semantics beyond the field docs.

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 ('Read the organization's notification feed') plus ordering and scope ('newest first'), then enumerates the concrete categories (audit_complete, issues_detected, audit_failed, broken_links, schedule_paused). An agent can tell this apart from list_issues or list_audits without opening any 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?

Gives an explicit when-to-use with example questions ('did last night's scheduled audit run?', 'what failed?') and names the alternative it replaces ('instead of polling every website'). The unread_only filter is framed by purpose ('just what nobody has looked at yet').

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that – catalog scale (300+ rules), the category groupings, and the fact that it lists rather than retrieves detail. It doesn't discuss pagination or result limits, but for a read-only listing the added data-structure context is solid.

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

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

Three sentences, front-loaded with the tool's scope, then filtering options, then the sibling hand-off. No filler and every sentence carries routing or scoping information.

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 usefully conveys what is returned (rules grouped into categories, with a categories list) and how to narrow results. Combined with the sibling routing to get_rule, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so all three parameters (search, category, include_categories) are already documented in the schema. The description reinforces category-code and keyword filtering but adds no syntax, format, or semantics beyond what the schema provides. 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?

States a specific verb+resource ('browse the catalog of 300+ audit rules') and immediately scopes it as a catalog/listing tool. It explicitly differentiates from the sibling get_rule ('Use get_rule for one rule's full detail'), so an agent can pick the right tool 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?

Gives clear selection guidance: filter by category code or search by keyword to locate a rule, and names the alternative get_rule for single-rule detail. The when-to-use and the alternative are both explicit, leaving nothing to inference.

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 it a safe read; the description adds real behavioral detail the annotations don't: the distinction between last_run_id (any status) and last_report_run_id (latest completed run with an undeleted report), the omission rules for unaudited/ephemeral sites, and that total/has_more drive pagination.

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 is front-loaded in the first clause and every subsequent sentence carries routing, exclusion, or pagination information. It is dense and slightly long, with the last_report_run_id point restated near the end, so it falls just short of maximal conciseness.

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 list tool with no output schema, the description fully covers row shape, the two key run-id fields, pagination fields, exclusion conditions, and the sibling calls to chain into. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by framing kind:'prospect' as the safe basis for a bulk-delete list and by tying last_report_run_id into get_report, which the schema cannot express.

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 ('List websites the organization has audited') and immediately enumerates the distinguishing payload (run status, health score, owned/prospect kind). It separates itself from siblings by naming list_audits for full history and get_report for reports.

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 routing: pass last_report_run_id to get_report, use list_audits with website_id for history, use website_id with list_issues/get_issue. It also states when-not (never-audited and ephemeral one-shot audits are excluded) and names add_website/run_audit as the registration path.

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 substantial behavior beyond the annotations: credit consumption, confirmation_required responses, sufficient true/false handling, cost and balance fields, upgrade_url, asynchronous runtime, automatic website registration, and recurring schedule costs. This is exactly the kind of mutation, cost, and multi-step workflow context an agent needs for a destructive, open-world tool.

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

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

The purpose is front-loaded and nearly every sentence carries actionable information for a complex, credit-spending audit tool. It is dense and presented as a single long paragraph, so it would benefit from clearer structure, but it avoids obvious filler given 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?

Given twelve parameters, no output schema, and annotations that only flag mutation/open-world/destructive behavior, the description is unusually complete. It explains the async workflow, confirmation edge cases, funding failures, level behavior, external-link costs, automatic registration, and recurring-audit schedule implications.

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 already documents all twelve parameters. The description still adds meaningful semantics for key parameters, including level tradeoffs, full-plan restrictions, max_pages: 1 as the cheapest run, external-link credit costs, and confirm behavior, though it does not discuss every parameter such as kind, scope, render, ephemeral, max_credits, or internal_links.

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 first sentence states a specific verb and resource: run a cloud audit of a website, including crawl, rule analysis, and report. It distinguishes this from sibling tools by identifying it as the audit starter and by naming the follow-up tools get_audit_status and get_report.

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 gives explicit usage conditions and exclusions: only for owned or authorized sites, optional confirm behavior, when to use dry runs, and how to choose level and max_pages. It also routes the agent to get_audit_status for polling and get_report for results, and explicitly says not to retry with confirm when funds are insufficient.

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 openWorldHint=true and destructiveHint=false, so the description's marginal value is the auth note: it works with any authenticated credentials including read-only API keys, which an agent might otherwise assume blocks a write-style call. It does not mention rate limits or what happens to the feedback afterward, keeping it below 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?

Two sentences, zero filler. The purpose and accepted content types come first, the usage trigger second, and the auth constraint last — a sensible front-loaded order.

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 needn't explain return values, and all four parameters are fully documented in the schema. Coverage is nearly complete; only a hint about confirmation or follow-up after submission is absent, which is minor for a fire-and-forget feedback 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 description coverage is 100%: the enum values, the 2000-char truncation, and the credential verification of run_id/website_id are all documented in the schema. The description restates the categories rather than adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and destination ('Send feedback to the squirrelscan team') and enumerates the concrete content types accepted (bug, missing feature, confusing, missing report data, ergonomics). No sibling tool covers feedback submission, so it is trivially distinguishable from add_website, comment_on_issue, 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 says when to use it ('when the user wants to report something or share their experience'), which is a clear trigger condition. It stops short of stating when not to use it (e.g. use comment_on_issue for issue-scoped discussion), so it is strong but not fully routive.

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?

Adds substantial behavior beyond annotations: plan-based clamping, dashboard-equivalent validation, confirmation_required flow with token and same-arguments retry, ownership verification semantics, and immediate application for schedule off or zero-cost changes. These details are not present in the structured annotations and are exactly what an agent needs for safe mutation.

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-loads the core purpose and proceeds through behavior in a logical order. It is necessarily detailed for a 15-parameter mutation tool, though the long initial field list makes it slightly denser than ideal.

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 complexity, full schema coverage, and absence of an output schema, the description supplies the missing behavioral context: what is stored, what the result reports, how confirmations work, and how plan limits affect values. Nothing critical for correct invocation is 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 100%, so the schema already documents all 15 parameters in detail. The description reinforces key fields and cross-parameter behavior, but does not add per-parameter semantics beyond what the schema provides.

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: 'Change one website's stored audit settings' and enumerates the settings affected. It is clearly distinguishable from read-only siblings such as get_website_settings without needing to name them.

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 when the tool applies and key conditions for use, including that omitted fields are unchanged, that some changes require confirmation, and that confirm_ownership is set only on the user's own word. It does not explicitly route the agent to get_website_settings for reading, so it falls just 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond them by disclosing exactly what the call surfaces (auth method, acting organization, plan, credit balance), which matters since no output schema exists.

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 tightly written sentences with no filler; the concrete return payload is front-loaded and the situational hint follows. Every clause carries information.

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 zero-parameter, read-only identity tool with no output schema, the description fully covers what an agent needs: what it returns and when it is useful. Nothing material 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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema coverage is 100% and has no properties, so no additional parameter guidance is possible or needed.

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 (identify) and resource (current credentials) and enumerates the concrete outputs: authentication method, organization, plan, and credit balance. This clearly distinguishes it from siblings like get_credit_balance, since it returns a bundle of identity context rather than a single value.

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 a clear usage context ('useful at the start of a session, to see which organization the other tools act for'), which tells the agent when to reach for it. It does not explicitly address overlap with get_credit_balance or state when not to use it, so it stops short of full exclusion guidance.

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