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?

Annotations already mark the tool read-only and non-destructive, and the description adds substantial behavioral nuance well beyond that: the removal-only-if-recrawled rule, the not-crawled fallback, coverage semantics, the key-change caveat that can mask fixed @ids, and how named runs are ordered chronologically. No statement contradicts 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 long but information-dense and front-loaded with the core output summary, followed by caveats and a practical workflow. Some concepts such as ordering and coverage appear both in the prose and in the schema descriptions, creating minor redundancy, but every sentence contributes useful 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?

With no output schema, the description carries the burden of explaining return semantics, and it does so thoroughly: gainedId/lostId, coverage values ('proven'/'partial'), not-crawled reporting, threshold effects, and the fix-and-verify loop are all specified. An agent has enough information to interpret results and handle common false negatives.

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 prose reinforces defaults, run_id precedence, website_id behavior, and threshold scope, but it does not add meaningfully new parameter-level semantics beyond what the schema already documents.

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 audits of a site and get the change set') and enumerates the exact outputs, including gained/lost @ids, occurrence changes, and conflicts. However, it does not explicitly differentiate itself from the similarly named sibling compare_audits, leaving the entity-focused scope to be inferred from the name and title.

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 concrete usage context, including defaults, chronological ordering, and a detailed fix-and-verify workflow with list_entities and run_audit. It does not state when to use compare_audits instead or provide exclusions, so it stops short of full when/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?

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 already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: progress field existence, health_score null for blocked sites, schedule field semantics, and that recurring audits auto-enable and cost credits. 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 a long dense paragraph covering many statuses and fields. While every sentence carries important information, it lacks visual structure (e.g., bullet points or separation of concerns) and could be more scannable for an agent. It is not overly verbose given complexity, but could be better organized.

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. It covers all statuses, progress fields, failure codes and next steps, health_score semantics, schedule details, and cost implications. Nothing an agent needs to interpret the response is missing.

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

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

The schema has 100% coverage for run_id with a description that already states its origin (from run_audit or list_audits). The tool description repeats this information without adding new semantics, so it provides no additional value over the 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?

The description clearly states the tool polls an audit by run_id, distinguishing it from run_audit (starting) and get_report (retrieving the report). It specifies the exact verb and resource, and names sibling tools that produce the 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?

Provides explicit when-to-use guidance: keep polling while pending/running, call get_report when completed, and act on failure codes when failed. It also explains the run_id source (run_audit or list_audits), making the intended workflow unambiguous.

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, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: the map keeps only nine properties plus @type, so missing properties may still exist in page JSON-LD; disagreements outside that set are not detected; edges and declaring pages are capped with counts indicating truncation; run_id resolution skips audits that stored no entities; and gainedId is the only confirmation that a fix landed. This is rich, non-obvious behavior disclosed clearly.

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 first sentence defines the return shape, the second explains the nine-property limitation, the third gives usage context, and the rest covers caps, run_id semantics, and the fix-and-verify loop. It is front-loaded with the core purpose and progressively adds operational detail. Slightly dense, but not 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?

For a read-only lookup tool with 100% schema coverage and no output schema, the description covers what the agent needs: what is returned, what is not returned, how key resolution works, how run_id defaults, how caps are signaled, and how to confirm a fix landed. The fix-and-verify loop even ties it to sibling tools. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the resolution order for key ('exact @id match, then exact key match, then id: prefix, then case-insensitive name, then substring') and by clarifying run_id's default behavior (latest audit that stored at least one entity, not necessarily the latest audit). It also explains website_id's local-vs-hosted behavior and precedence. This goes beyond the schema, so a 4 is warranted.

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 ('Get one entity as the map recorded it') and enumerates exactly what the returned entity includes: the nine kept properties, declaring pages, disagreements, and references. It also distinguishes itself from siblings by naming list_entities, compare_entities, and get_entity_findings/get_entity_graph implicitly through scope. This is a clear, specific purpose statement.

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: 'Use this after list_entities to see why an entity was flagged, before deciding what to change.' It also provides a full fix-and-verify loop naming list_entities, run_audit, and compare_entities, and explains when to pass run_id ('If you are checking whether a change landed, name the run'). This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the agent knows it's a safe read. The description goes far beyond by disclosing that findings are samples: 'the pages listed are never the complete affected set and no field reports how many were left out.' It explains the analyzed flag as a false-positive guard ('empty findings are an absence of evidence rather than a clean result'), and details the coverage field semantics ('proven' vs 'partial'). It also clarifies that gainedId is the only confirmation of a fix. 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 long but every sentence earns its place: it front-loads the core purpose in the first sentence, then layers critical caveats (sampling, analyzed flag) and a procedural workflow. It uses paragraph breaks for logical grouping. While it could be tightened, it avoids fluff and repetition, so the length is justified by 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 the tool has no output schema and the operation is a read of a complex graph-analysis result, the description covers all necessary aspects: what findings represent, how to interpret counts and samples, the meaning of the analyzed field, the exact workflow to verify fixes, and the semantics of coverage. There are no gaps that would leave an agent uncertain about how to invoke the tool correctly or interpret its results.

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 provides full descriptions for both parameters (run_id and website_id), achieving 100% coverage. The tool description adds valuable context beyond the schema: it explains the default selection behavior for run_id (latest audit that stored at least one entity, and why), warns about audit runs being passed over, and clarifies the precedence between run_id and website_id. This enriches the schema, though the schema already carries the core semantics.

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 statement of what the tool returns: 'schema/entity-* rule verdicts for an audit', specifying the resource (audit), the nature of the data (verdicts on entity graph problems), and the granularity (findings across the whole site). It explicitly differentiates itself from re-deriving problems manually and names the alternative tool list_entities for the full affected set, which distinguishes it from siblings.

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 when-to-use guidance: 'Use this instead of re-deriving the problems from the graph yourself.' It also provides a complete fix-and-verify loop with explicit steps (call list_entities with problem='no-id', assign @id, re-run audit with run_audit, then call compare_entities and check gainedId). It further explains when NOT to rely on findings (sampled lists) and when to check the analyzed flag to interpret empty results. This is explicit 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?

Annotations already mark this as read-only/non-destructive, and the description adds substantial behavior beyond that: mermaid/markdown caps, 'no cap is not the same as complete,' local-server missing arrays, per-server format refusal, run_id pass-over warnings, and gainedId/coverage semantics. 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?

Front-loaded with the core action and format list, then proceeds through cap behavior, server differences, and the verification workflow. It is long, but dense with non-redundant caveats; only the extended fix-and-verify digression keeps it from being maximally concise.

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

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

For an 8-parameter tool with no output schema, the description covers return formats, truncation, empty-array semantics, server capability differences, and the post-fix verification contract (gainedId, coverage field). There is no obvious gap for an agent deciding how to call it and interpret 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining format purposes and caps, clarifying that filters match list_entities, and giving run_id selection nuance ('Defaults to the latest audit that stored at least one entity'). This elevates 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 action and resource: 'Get the whole entity graph, or a filtered part of it, in a chosen format.' The six formats and the note that it accepts the same filters as list_entities make the tool's scope unmistakable and separate it from get_entity/list_entities.

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 concrete format-selection guidance ('mermaid or markdown to read in a conversation, dot or graphml for a graph tool') and embeds the tool in a fix-and-verify loop where list_entities, run_audit, and compare_entities are explicitly named. It also tells the agent when list_entities is the right call ('call list_entities with problem="no-id"').

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?

The annotations declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond annotations: provenance semantics (carried/unrendered), seedRedirect behavior, FAILED/BLOCKED status keys, and the explicit note that null healthScore + empty topIssues mean failure not cleanliness. It also clarifies that the report is the source of truth for numbers, providing critical interpretation guidance.

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 for a complex report tool. It is front-loaded with the core purpose, then progressively covers formats, provenance, redirects, failure states, and count comparisons. The structure organizes a large amount of essential information 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?

The description covers all critical behaviors an agent needs to correctly interpret results: provenance, redirect handling, failure modes, format differences, and count relationships with sibling tools. It even warns against misinterpretations ('not one row per page', 'read N pages from count, not row total'). The lack of an output schema is fully compensated.

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 three parameters. The description adds meaningful semantics beyond the schema for format (explains what each format contains and when to use each) and clarifies default behavior, though top_issue_limit isn't elaborated beyond the schema. Since the schema carries the parameter documentation and the description adds usage semantics, a 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 identifies a specific verb ('Fetch'), a resource ('finished report for an audit run'), and the relationship to run_audit/get_audit_status. It clearly distinguishes itself from sibling tools by focusing on report retrieval for a specific run, not issue management, comparisons, or audit triggering.

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 tells the agent when to use get_report (after get_audit_status shows completed) and how to sequence calls: use run_id from run_audit, use list_audits to page history, start with summary then pull llm/markdown. It also names sibling alternatives and explains how counts relate to list_audits/get_audit_status/list_issues, making the usage context explicit.

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 only declare readOnlyHint=true and destructiveHint=false, which are baseline. The description adds substantial behavioral context: the collapse by resolved @id or by type/name, the split-identity problem, the pagination contract (hasMore), the run_id default behavior (latest audit that stored at least one entity), and the meaning of the 'coverage' field ('proven' vs 'partial'). It also explains the gainedId confirmation in compare_entities. This goes far 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 long but densely packed with necessary information. It is front-loaded with the core purpose and collapsing behavior, then expands into filtering, pagination, and the fix-and-verify loop. While every sentence earns its place, it could be slightly more structured with bullet points or paragraphs, but given the complexity it remains appropriately sized.

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 9 parameters, no output schema, and many behavioral subtleties, the description covers the essential aspects: the collapsing rule, split-identity problem, filtering options, pagination, run_id defaulting, include_page_local, and the fix-and-verify workflow including the interpretation of coverage. It also mentions the return shape (filtered summary, page of nodes, total, hasMore). Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantic context beyond the schema: it explains the filtering options in plain terms (filter by @type, page, problem, name), the include_page_local rationale, and the nuance of run_id (that it defaults to the latest audit that stored entities, not necessarily the latest audit). It also clarifies the meaning of the problem enum values indirectly through the workflow. These enrich 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 'List' and the resource 'entities a site declares in its JSON-LD', and immediately clarifies the collapsing behavior across pages. It distinguishes itself from siblings like get_entity (which likely retrieves a single entity) and compare_entities by its aggregation scope. The mention of split-identity further disambiguates it from a naive list.

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 guidance on when to use this tool: in the fix-and-verify loop it says 'call list_entities with problem="no-id"' and then follow with run_audit and compare_entities. It also warns against relying on a single page by instructing to 'keep requesting pages while hasMore is true'. It explicitly names alternatives and the workflow sequence, leaving no ambiguity.

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?

The description goes well beyond the annotations, disclosing credit costs, pay-as-you-go behavior, asynchronous execution, automatic website registration, recurring schedule side effects, and the refusal behavior when confirmation is retried. This is substantial behavioral context that the annotations alone do not 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 long, but every sentence carries necessary operational information for a complex pay-as-you-go async tool. It front-loads the core purpose and immediately proceeds through cost confirmation, sizing, async flow, and side effects, with no filler or 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?

Given 9 parameters, no output schema, and a non-trivial async workflow, the description covers the critical runtime behavior: confirmation states, fields to relay, retry refusal, run_id polling, automatic registration, and recurring audit scheduling. An agent has enough information to invoke the tool correctly and handle its responses.

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?

All 9 parameters are already documented in the schema (100% coverage), so the baseline is met. The description adds real operational meaning for confirm (threshold flow), max_pages (entry-URL cheapest run), and the schedule side effect, though it does not add much beyond the schema for render, coverage, kind, or max_credits.

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

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

The description names a specific verb and resource ('Run a cloud audit of a website') and gives a concrete breakdown of what that entails: crawl + 260+ rule analysis + report. It is clearly distinguishable from siblings like get_audit_status and get_report because it is the action that starts the audit rather than polling or fetching results.

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 and how-to-proceed guidance: how to confirm credit spend, what to do when confirmation_required is returned, what to relay when sufficient is false, and to not retry with confirm: true. It also directs the agent to poll get_audit_status and then fetch with get_report, making the full invocation workflow unambiguous.

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.