QuassLabs API

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

With no annotations, the description carries the burden and does well: it discloses the analysis is deterministic with no LLM, and enumerates exactly what the response contains (per-AC problems, missing failure-path coverage flag, score, verdict). It omits side-effect/auth/rate-limit disclosure and whether both inputs can be combined.

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 role and action, then outputs, then the determinism claim. Dense but every clause carries information; only the 'QA advisor:' framing and 'Tells you exactly what to fix' are slightly promotional.

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 does a good job describing the return shape. However, for a 3-parameter tool it never explains strictness behavior, whether story and acceptance_criteria are mutually exclusive, or what happens if neither is supplied (required list is empty).

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

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

Schema coverage is 0%, so the description must compensate. It maps 'a list of AC' to acceptance_criteria and 'or a story' to story, but the strictness enum (normal/strict) is never mentioned anywhere, leaving a third of the parameters undocumented.

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

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

States a specific verb and resource: 'validate acceptance criteria quality', with concrete outputs (per-AC problems, coverage flag, 0-100 score, verdict). It does not differentiate itself from close siblings like story_lint, ticket_lint, or coverage_check, so an agent must infer the boundary.

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?

'POST a list of AC (or a story)' implies the two input modes, but there is no explicit statement of when to pick this over coverage_check or story_lint, nor any exclusion or prerequisite. Usage is inferable 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?

With no annotations provided, the description carries the full behavioral burden. It usefully discloses the evaluation scope and output shape, including letter grade, numeric score, per-flag remediation, and pass/fail verdict. It does not state whether the operation is read-only, whether prompts are sent externally, or whether there are privacy or rate-limit considerations.

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 tight sentences with no wasted text. The primary action is front-loaded, and the return values are summarized 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 three-parameter evaluation tool with no output schema, the description sufficiently covers what the tool does and what it returns. The main missing element is guidance on when to use it versus sibling validators/scorers, not invocation-critical information.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description reinforces that the system prompt is the input and agent config is optional, but it does not add meaningfully more parameter-level guidance beyond the schema baseline.

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

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

The description uses a specific verb and resource: it runs a system prompt (and optional agent config) through a 45-criterion alignment/safety rubric. It also states the output clearly. It does not compare itself to sibling validation or scoring tools, so it falls short of 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?

The usage context is implied: this is the tool for evaluating an AI system prompt against an alignment/safety rubric. However, the description gives no explicit when-to-use guidance, no exclusions, and does not name alternatives such as readability_grade or humanizer_score.

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 no annotations, the description carries the full behavioral burden. It helpfully discloses the types of results returned, which clarifies what a caller gets. But it does not state freshness, coverage limitations, error behavior for coordinates outside BLM land, or whether the lookup is purely read-only.

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 sentence that front-loads the core action and then lists relevant result categories. There is no wasted language, and every clause contributes useful 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 three-parameter lookup with no output schema, the description does well by enumerating the returned information categories. It is nearly complete, though it omits edge-case behavior such as coordinates outside BLM jurisdiction or how coverage gaps are handled.

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 all three parameters are already documented in the input schema. The description adds only the implicit coordinate context and result types, not parameter-specific semantics beyond the schema baseline.

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

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

The description uses a specific verb and resource: look up BLM land status for a US coordinate. It also enumerates the exact kinds of information returned (ownership, jurisdiction, activities, permits, designations), making the tool's purpose unmistakable and distinguishing it from unrelated sibling tools.

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

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

The phrase 'for a US coordinate' gives clear usage context and geographic scope, which is important for a location-based lookup. However, there are no explicit exclusions or alternative tools named, and no guidance on when not to use 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?

With no annotations, the description carries the full burden and does so well: it discloses the human-in-the-loop requirement (hand checkout_url to a human to pay in a browser), the asynchronous fulfillment behavior (credits added automatically within seconds of payment), and that calling the tool itself charges nothing and consumes no credits.

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 action and result, and every sentence carries operational value. Minor redundancy: pricing is given three times ($5/500, $20/2500, and 1 credit = $0.01) and duplicated again by the schema.

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, and the description compensates by naming the returned field (checkout_url) and explaining what happens after payment. For a two-optional-parameter tool this is fully sufficient to call 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 both `pack` and `packs` are already documented, including the enum values and pricing. The description restates the same pack pricing rather than adding new semantics (e.g. how `packs` interacts with the checkout URL or whether it multiplies the charge).

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

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

States a concrete verb and resource ("Get a Stripe Checkout link to top up the credits") and pins the scope to the calling API key. No sibling tool does anything similar, so no differentiation is required.

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 context of use is clear (topping up credits) and it explicitly notes that invoking it costs nothing, which tells the agent it is safe to call speculatively. It never states when not to call it or what the alternative is, though no plausible alternative exists among the 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?

With no annotations, the description carries the burden and does well: deterministic, no LLM, no network, message-only scanning, batch cap, and the large-commit threshold derived from caller-supplied insertions/deletions. It does not disclose the shape of the returned findings, which is a remaining gap given there is no output schema.

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 with the tool's identity followed by the checklist and the message-only scope caveat. It reads as one long run-on sentence, but nearly every clause adds a distinct check or constraint, so little 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 multi-check validator with no annotations and no output schema, the description omits the return format: whether findings are a list, how severity is reported, or what a clean result looks like. Input semantics are complete, but an agent cannot anticipate the response shape.

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, but the description adds real meaning: max_lines_changed is a threshold on insertions+deletions that triggers a large_commit finding, and insertions/deletions are caller-supplied rather than computed. It also clarifies the commit vs commits alternative and the batch ceiling.

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 (commit-message hygiene checker) and enumerates the exact checks it performs: conventional format, vague subjects, subject length, secret patterns, oversized commit. This clearly separates it from siblings like pr_description_lint and regex_lint, which operate on different artifacts.

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 operating context: POST one commit or a batch up to 200, and explicitly scopes the secret scan to message text, never a diff. It does not, however, state when to prefer this over a sibling linter or any prerequisites/exclusions for use.

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 no annotations, the description carries the full burden, and it does disclose meaningful traits: rendering occurs on the provider's infrastructure, content is not sent to third parties, and inject_lightbox injects CSS+JS. It does not cover failure behavior for malformed Mermaid, size or rate limits, or whether output is deterministic — gaps that matter for a transformation tool with zero annotation coverage.

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

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

Front-loaded with a one-line purpose, then input/output contract, then the rationale, then a privacy note — a sensible order. The middle sentence ('A CDN-backed diagram only renders if...inline SVG needs neither') is somewhat redundant with the first, costing a little density.

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, so the description must explain return values, and it does: the same document with inline SVG, or raw SVG when output_format=svg. Privacy handling is covered. Missing is any statement of behavior on invalid Mermaid input or partial-failure handling, which an agent would want before calling.

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%, including mutual exclusivity between html and mermaid_source and the svg-requires-mermaid_source constraint, so the schema does the heavy lifting. The description adds only indirect color via the portability framing (why inline SVG) and nothing about theme, background, or the lightbox semantics beyond what the schema states. 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 transformation: takes HTML with <div class="mermaid"> blocks or raw Mermaid source and returns the same document with diagrams pre-rendered to inline SVG and the CDN runtime stripped. The verb+resource+output are unambiguous. It does not, however, distinguish itself from diagram-adjacent siblings like describe_diagram or diagram_contrast, so it stops short of 5.

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

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

Gives concrete use contexts — offline readers, email clients, Notion/Confluence that strip <script>, and PDF export — which is exactly the 'when to use' signal an agent needs. It stops short of explicit exclusions or naming an alternative tool to use instead.

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 no annotations, the description carries the full behavioral burden. It discloses that the tool is deterministic and uses no LLM, which is valuable, and it lists the output categories. However, it does not explicitly state whether the operation is read-only or has side effects, nor does it mention permissions, rate limits, or idempotency—gaps that matter for a POST endpoint.

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, front-loads the tool's purpose, and then efficiently enumerates inputs and outputs. Every phrase contributes useful information without repetition or fluff.

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

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

Given the absence of an output schema and annotations, the description does a good job of explaining the return values (coverage score, gaps, orphan stories, missing buckets) and the deterministic nature. It is almost complete for calling the tool, though it could be slightly richer about input expectations and safety profile.

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

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

Schema description coverage is 0%, so the description must compensate. It names all three parameters and clarifies that 'brief' and 'requirements' are alternative sources while 'stories' are the items to check, which adds meaning beyond the schema. It still does not explain expected formats, whether both brief and requirements can be supplied together, or precedence rules, leaving some ambiguity.

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 role label ('Scope-completeness advisor') and then states exactly what the tool does: accepts a brief/requirements and stories, returns a coverage score, gaps, orphan stories, and missing structural buckets. This clearly distinguishes it from sibling linting and validation tools by focusing on requirement-to-story coverage rather than criteria quality or ticket formatting.

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 provides clear context by describing the inputs and outputs, implying usage when you have a brief/requirements and user stories and want to find scope gaps. It does not name alternatives or state when not to use it, so it falls short of a 5, but the context is sufficiently clear for an agent to select 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?

With zero annotations the description carries the full burden and does well: it discloses the exact return fields, states list-mode behavior differs (ranking + duplicate clustering), and explicitly says "Deterministic, no LLM" — meaningful behavioral context an agent cannot infer elsewhere. It omits cost/credit implications and error behavior, which keeps it from the top mark.

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 tight sentences: identity first, then outputs, then batch-mode delta and the determinism guarantee. Every clause carries information and nothing is repeated from structured fields.

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 and no annotations, so the description has to describe returns — and it does, naming severity levels, category, repro flag, and missing-info categories. The remaining gap is the zero-argument / conflicting-argument case, which matters since required parameters is 0.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partly does: "one bug report (or a list)" implies the report/reports split but never names the parameters, never says they are mutually exclusive or which wins if both are sent, and never says what the string content should look like. Partial compensation warrants a 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?

"Bug-triage advisor" plus an explicit output list (severity, category, repro detection, missing info, and for lists priority ranking and duplicate clusters) makes the operation concrete and unmistakably distinct from validation-oriented siblings like ticket_lint or story_lint. It stops short of 5 only because it never names the neighbouring tools it is not.

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?

"POST one bug report (or a list)" gives input-shape guidance and the list mode hints at the batch use case, but there is no explicit when-to-use / when-not, no prerequisites, and no pointer to an alternative tool for adjacent tasks. Usage 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?

With no annotations at all, the description carries the burden well: it discloses determinism, no network, no LLM, and that the compromise check is against a static snapshot rather than live data. It doesn't state whether posted manifest content is persisted or how large an input can be before failing.

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 tightly packed sentences: purpose and inputs first, output shape second, boundary/exclusions third. Every clause carries information; nothing is repeated or 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 3-param tool with no annotations and no output schema, the description supplies the missing behavioral context (what a finding contains, determinism, static data limits). It stops short of describing pagination or result ordering, which an agent might want.

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 filename, manifests, and upload_id including the either/or relationship. The description's 'POST ... or an upload_id' restates that relationship without adding format, size, or validation 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 ('Dependency-manifest hygiene check') and then enumerates the exact input types and finding categories, so an agent knows precisely what comes back. It does not differentiate itself from the sibling supply_chain_scan, which is the closest functional neighbor.

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?

'NOT a live CVE feed - pair with npm audit / pip-audit / osv-scanner for that' is an explicit when-not plus named alternatives, and the two invocation modes (inline manifests vs upload_id) are called out. Missing only guidance against the in-house sibling (supply_chain_scan / coverage_check style tools).

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

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

With no annotations present, the description carries the full behavioral burden; it does disclose the generation backend (AWS Bedrock) and a data-handling guarantee, which is real added value. It omits error behavior for unparseable descriptions, latency/rate-limit expectations, and whether output is guaranteed valid Mermaid beyond the claim of 'complete, valid' source.

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 the example plus pipeline note earn their space. The closing sentence about AWS Bedrock is tangential to invocation but buys legitimate transparency, so it is defensible rather than wasteful.

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

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

For a two-parameter generation tool with no output schema, the description covers input style, diagram-type behavior, and the return value's usable field. Only streaming/error semantics for failed generation are left unaddressed.

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 both parameters, including the full diagram_type enum, are already documented in the schema. The description's example ('a login flow with an OAuth branch and a failure path') illustrates the description parameter's style but adds no rule beyond what the schema 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 and resource: turn a plain-English description into Mermaid diagram source. It also distinguishes itself from the sibling convert_diagram by framing the pair as a describe -> render pipeline, so an agent can pick the right one without opening the schemas.

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

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

Gives a concrete input example and explicitly routes to convert_diagram for the rendering step. It does not spell out the inverse case (if you already have Mermaid source, skip this and call convert_diagram directly), so the when-not guidance is only 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?

With no annotations, the description carries the full burden and does well: it discloses deterministic behavior, no AI, no rate limit, honest flagging of unresolvable fills, and the mode-specific outputs. It does not cover error behavior, input prerequisites, or whether harden rewrites the source in place versus returning a new source.

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

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

The description is front-loaded with the core purpose and uses a numbered list to organize the four capabilities. It is dense but justified by the multi-mode tool, with only minor verbosity in the parenthetical explanations.

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 11-parameter tool with no annotations and no output schema, the description is fairly complete: it explains each mode's purpose, key behavior, and the type of result returned. It could be stronger by clarifying output shape, error cases, and whether any mode writes or mutates external state.

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 parameter documentation is already strong. The description adds useful meaning beyond the schema by explaining the distinctions among scan, harden, contrast, print, and layout, including why source hardening cannot be achieved by scanning rendered output.

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 purpose, 'Diagram quality QA,' and enumerates four concrete capabilities: contrast checking, mermaid source hardening, print-safety checks, and arrow-crossing reduction. It is clear what the tool does, though it does not explicitly differentiate itself from diagram-adjacent siblings such as convert_diagram or describe_diagram.

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?

Each mode is given a clear usage scenario, and the description explains why source hardening is distinct from rendered scanning. It stops short of naming when not to use the tool or pointing to specific alternative sibling tools.

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

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

With no annotations, the description carries the full burden and does most of it: it discloses determinism ('no LLM'), that no benchmark numbers are built in, that unbenchmarked types are never guessed at, and the precedence rule. It stops short of stating that the endpoint is side-effect free / persists nothing, and the 'POST' wording could momentarily read as a write.

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 classification behavior, then input modes, then limits — a sensible order with essentially no filler. The middle sentence about ranges-vs-historical is long and slightly run-on, but every clause conveys a real constraint.

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 6-parameter tool with nested objects and no output schema, the description covers inputs, precedence, and the vocabulary of returned flags. It leaves the response shape (per-item structure, aggregate counts, error behavior when called with zero parameters) unspecified, which is the main residual gap.

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; the description still adds cross-parameter semantics beyond the schema — that benchmarks override historical per type and that a type with neither input yields 'unbenchmarked'. It does not clarify how 'estimate' vs 'estimates' interact or whether supplying both is an error.

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 gives a specific verb+resource+method: a deterministic classifier for story/task hour estimates against benchmarks, and it enumerates the exact output labels (in_range, borderline, over, under, unbenchmarked). No sibling in the list does estimate-vs-benchmark classification, so an agent can route here without ambiguity.

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 the two input modes (explicit {min,max} benchmarks vs. historical actuals) and the precedence rule when both exist, plus the batch ceiling of 200. It does not name an alternative tool or say when to prefer it over, say, sprint_health, but the operational context for invoking it is complete.

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 no annotations, the description carries the full burden and does disclose real behavioral facts: auth is required, the submission is tied to the caller's key, it is not billed, and no SLA is implied. It does not describe what happens after submission (confirmation, rate limits, whether duplicate submissions are deduplicated), which keeps it short of 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 tight sentences with the core purpose front-loaded. Slightly wasteful: "not billed" appears twice ("not billed and not a support-ticket SLA" then "Auth required; not billed"), which could be trimmed without loss.

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, five-parameter submission tool with no output schema, the description covers purpose, auth, billing, and follow-up intent adequately. The only gap is what the caller gets back after submitting, but with no output schema there is limited obligation to explain returns.

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 every parameter including enums and defaults is already documented. The description only loosely echoes the category options ("a bug, a feature request, a docs gap, a billing question") and implies contact_ok via "so we can follow up," adding 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 ("Submit free-text feedback about the API") and enumerates the accepted subject matter — bug, feature request, docs gap, billing question — so the agent knows exactly what fits. No sibling tool offers feedback submission, so there is no ambiguity to resolve.

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 draws a clear boundary by noting this is "not a support-ticket SLA," which tells the agent this is not the path for urgent issue escalation. It gives context for use but does not name an alternative tool or state explicit exclusions (e.g., when to use a real support channel instead).

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 no annotations, the description carries the full burden and does so well: it names the categories of change (vocabulary swaps, filler stripping, em-dash reduction, significance deflation), states exclusions (protected spans), declares determinism and no LLM, and discloses that some tells are deliberately left for human judgment. This is exactly the context annotations would otherwise supply.

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 the mechanical-fix list, with the sister-tool pointer saved for last. It is dense — the long parenthetical enumerations make it run-on — but no sentence is 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, yet the description covers the return payload (rewritten text, change log, before/after ai-ness scores, residual tells list), which is the main gap a caller would otherwise have. Combined with the preservation and determinism notes, an agent knows everything needed to invoke 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?

Only one parameter (`text`) and schema description coverage is 100%, with the 100k character limit already documented in the schema. The description's 'POST prose' framing adds nothing beyond what the schema declares, so 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?

Opens with a specific verb+resource ('Rewrite text to remove AI-writing tells') and immediately frames the mechanism (POST prose, get it back fixed). It explicitly distinguishes itself from the sibling detector humanizer_score, so an agent can route between them 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?

The 'Sister to humanizer_score (the detector)' line implies the intended split — use this to fix, use that to measure — and the preservation rule (code fences, inline code, URLs, quotes never touched) sets a clear boundary on what input is appropriate. It stops short of explicit when-not-to-use guidance or a prerequisite like 'only for prose, not code files'.

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 no annotations, the description carries the full burden and does well: it declares determinism, no LLM involvement, explainability, the exact shape of returned patterns, and that no rewrite occurs. It omits operational traits an agent would want, such as whether the call consumes credits (a buy_credits sibling exists) or any rate/latency characteristics.

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: purpose, return shape, pattern taxonomy, and the rewrite boundary all land in a few tight sentences. A slight dip into marketing register ('Explainable, not an opaque classifier') is redundant with 'every point is a named, located pattern', which says the same thing more concretely.

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 describe the return value, and it does so completely: score range, band values, fired patterns with sample spans. Combined with the schema-documented input, an agent has everything needed to call 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% and there is only one parameter, whose 100k-char limit is already documented in the schema. The description adds nothing about the text parameter beyond the implied 'POST prose' framing, so the 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?

Specific verb and resource ('Detect AI-writing tells in text') followed immediately by a concrete explanation of what comes back: a 0-1 ai_ness score, a band, and the exact named patterns with sample spans. The closing line 'The rewrite is a separate step' distinguishes it from the sibling humanize tool without the agent needing to open 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?

The description makes the division of labour clear: this tool scores, the rewrite is a separate step, which effectively routes the agent to humanize for rewriting. It also frames the tool's niche ('explainable, not an opaque classifier'), which tells the agent why to pick it. However, it never explicitly states when NOT to use it or names the sibling directly.

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?

Since no annotations are provided, the description carries the full burden, which it handles excellently. It explicitly details complex behaviors like normalized error signatures, log gap detection, and generating templated recommendations.

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?

While dense, the description is extremely efficient; every phrase communicates a specific functional capability or constraint. It front-loads the core function and outputs.

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 complex multi-part output (breakdown, clusters, anomalies, recommendations), the description provides a complete blueprint of what an agent can expect as a result. It removes ambiguity about 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?

With only 75% schema coverage, the description compensates significantly by adding constraints (5MB upload limit) and detailed format compatibility that maps directly to the `format` parameter.

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

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

The purpose is stated clearly: 'Analyze a log file.' It distinguishes itself from sibling tools (which are mostly code-focused) by clearly defining the scope of log processing and the types of analysis it provides.

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 excellent operational guidelines by defining acceptable input formats (JSON-lines, ISO8601/syslog/CLF/epoch) and input delivery methods (raw text vs. `upload_id`). It also provides a critical behavioral guide by stating it is 'Deterministic, single-pass, no LLM.'

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 no annotations and no output schema, the description carries the disclosure burden well: it enumerates what comes back, states 'Deterministic, no LLM', and warns that retention/compliance figures are common-practice defaults to verify with counsel. Only idempotency/rate-limit behavior is left unstated, which matters little for a stateless generator.

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 deliverable list and the input requirement are front-loaded, and every clause (outputs, implementability, determinism, legal caveat) carries distinct information. No redundant restatement of the tool name.

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?

Without an output schema, the description's enumeration of return contents is exactly what an agent needs, and the determinism plus legal caveat cover trust concerns. The one hole is the unexplained 'stack' parameter.

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

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

Schema coverage is 50%: 'features' and 'description' are documented in the schema, and 'compliance' is self-documenting via its enum. The description adds that compliance targets are optional but never explains 'stack', leaving one parameter undocumented in both places. Baseline 3 fits when the schema does most of the work.

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?

A specific verb (Generate) plus a precise resource (concrete audit-logging spec) and an enumerated set of deliverables: event catalog, envelope schema, storage plan, compliance notes. No sibling could be confused with this one — log_analyzer analyzes logs while this produces a spec.

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?

Clearly frames the call as 'POST your feature list (and optional compliance targets)' and states the outcome is directly implementable by a dev team. Use context is clear, but there are no explicit exclusions or named 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?

With no annotations, the description discloses useful behavior: it is deterministic and does not call an LLM, it is backed by a maintained model+price catalog, and it returns a fallback chain plus an explicit do-not-use list with reasons. It would be stronger if it stated whether the call has any side effects or external dependencies beyond the catalog.

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 and short, but written in terse fragments ("A maintained model+price catalog.") and the closing sentence ("Tells the AI/user which model to use and what it costs") largely restates the opening, costing efficiency.

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

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

For a 7-parameter tool with no output schema and no annotations, the description adequately conveys the return shape (primary+fallbacks, do-not-use with reasons, complexity tier, per-run and monthly cost). Gaps remain around the undocumented numeric parameters and any runtime constraints.

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

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

Schema coverage is only 29% (only top_n and models are documented), so the description must compensate, and it does: it explains volume/tokens inputs and gives concrete examples for the undescribed constraints array (local-only, cheap). It still doesn't clarify tokens_in/tokens_out defaults or volume_per_month units.

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: an LLM selection and cost advisor that takes a task description and returns a recommended model, fallback chain, and cost. It is clearly distinguishable from siblings like tool_advisor or buy_credits, which concern tool choice and purchasing rather than model selection.

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

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

The description implies usage ("POST a task description... get a recommended model") but never states when an agent should call this versus another tool, nor any exclusions. No alternatives are named and no prerequisites are given.

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 no annotations, the description carries the burden and does well: it discloses determinism, absence of LLM, the exact flag conditions, the conditional bugfix rule, and the single-PR limit. It stops short of saying what a finding/result looks like or whether 'pass' returns an empty list, which an agent needs to interpret results.

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

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

Front-loaded with the identity of the tool and followed by an efficient rule enumeration; almost nothing is wasted. The single run-on sentence with stacked em-dashes makes the conditional bugfix rule slower to parse than a short list would.

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 never states the shape of the result (list of findings? per-rule messages? severity?), which is the main gap for a linter. Inputs and trigger conditions are otherwise well covered for a two-parameter 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 both parameters are documented there, so the baseline is 3. The description adds only modest value beyond the schema: it mentions an explicit is_bugfix flag and that the issue reference is optional, but it does not explain the accepted forms of an issue reference (e.g., '#123' vs a ticket URL) or how body/title still influence the bugfix heuristic beyond the prefixes listed.

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

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

Names a specific verb and resource ('PR description quality linter') and enumerates the exact rule set: short/missing body, missing test evidence, missing rationale, unstructured long body, bugfix-only repro steps, optional issue link. 'Single PR only, no batch' and 'no LLM' further pin down what it is versus lint siblings like ticket_lint or commit_hygiene.

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 scopes usage ('Single PR only, no batch') and states the conditional trigger for repro-step checks (title prefix fix/bug/hotfix/patch, or is_bugfix). It does not name an alternative tool to use instead when the PR is part of a batch or when a broader ticket check is wanted, so routing to a sibling 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?

With no annotations, the description carries the load and does well: it discloses overwrite-on-resubmit idempotency, that auth is required, and that the call is not billed. It doesn't say whether ratings are visible to others or how failures surface, but the key write-semantics and cost profile are covered.

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 tight sentences, front-loaded with verb, target, and key parameter, then scope, then write semantics, then cost. No sentence is filler; each carries a distinct constraint.

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 three-parameter write tool with no annotations and no output schema, the description supplies the scope, the keying mechanism, idempotency, auth, and billing behavior. 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 67% (only `rating` lacks a schema description, and its enum is self-explanatory). The description adds real meaning beyond the schema by explaining that request_id must come from the response of the call being rated, which is the main place an agent could go wrong.

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

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

Specific verb and resource: rate a prior metered call with thumbs up/down plus optional comment, keyed by request_id. Scope is narrowed to 'compress calls' so an agent knows what is rateable. It does not explicitly contrast with the sibling `feedback` tool, which is the one plausible alternative an agent might confuse this 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?

States the operating condition clearly: tell us when a compression was too aggressive or dropped something. Current scope (compress calls only) is stated as a constraint, which prevents misuse. No explicit when-not or named alternative, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does so: it discloses determinism twice, states no LLM is involved, and proactively flags the syllable-counting approximation ('standard vowel-group heuristic... not a dictionary lookup'). That caveat is exactly the kind of behavioral trait an agent can't infer from 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?

Front-loaded with purpose and output set, then caveats and the sibling distinction in descending priority. Slightly dense and the determinism claim is restated at the end, 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?

No output schema exists, so the description must enumerate return values — it does (counts, reading-ease band with its range, optional on_target flag). Combined with the heuristic caveat and sibling disambiguation, 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 baseline is 3; the description earns more by explaining the effect of target_grade — it produces an on_target flag and the tolerance is +/-2.0 grade levels, which the schema does not state. The 100,000-character limit is covered by the schema rather than repeated.

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

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

Names the exact metrics (Flesch Reading Ease, Flesch-Kincaid Grade Level) and the exact input (a block of text), plus the auxiliary outputs it returns. It also explicitly separates itself from the sibling humanizer_score, so an agent can choose between them without opening a 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?

Explicitly routes the agent away from the adjacent metric family ('Different metric family from humanizer_score - this is pure readability statistics, not AI-writing-tell detection') and explains the optional target_grade path. It stops short of stating when-not-to-use (e.g. non-prose input) but the context is clear.

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 no annotations, the description carries the full burden and does well: it discloses that the pattern is compiled but never executed, that detection is a structural AST heuristic, and that the tool is deterministic with no LLM. The remaining gap is the absence of any statement about the return shape (findings, risk levels, explanation), which matters because there is no output schema.

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 purpose, then the detection categories with concrete examples, then the critical safety caveat. Every sentence carries information an agent would otherwise have to guess; nothing is padding.

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

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

For a two-parameter analysis tool with no annotations, it covers the essential behavior and limits. Without an output schema it should say more about what comes back — e.g., a risk verdict plus explanation fields — rather than only hinting at it via "a risk of 'none'."

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 both `pattern` and `flags` are already documented in structured data; the description adds no new syntax or constraints beyond restating the pattern. Baseline 3 applies when 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 specific verb+resource — static safety analysis of a regular expression — plus an auxiliary output (English explanation of what it matches). It is unmistakable against lint siblings like story_lint, ticket_lint, and pr_description_lint, which lint prose/config rather than regex structure.

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 makes clear the operating context (ReDoS/backtracking risk analysis) and adds a usage caveat: a risk of "none" means no known dangerous shape was found, not a proof of safety. It does not name an alternative tool or state when-not to use it, so it stops short of the top band.

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 no annotations, the description carries the burden and does disclose useful traits: the math is deterministic, an LLM is not involved, and the response includes per-metric health tags, an overall grade, and a ranked focus list. It does not state whether inputs are persisted or whether results are cached/reproducible across versions, which is the remaining gap for a compute 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?

Two dense sentences with the input contract first and the output list second; every clause adds information and there is no filler.

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

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

No output schema exists, so the description must enumerate the return value, and it does so concretely (metric set, health tags, grade, ranked focus list). What remains thin is input-side detail — units and the meaning of the optional-but-unnamed fields — for a 10-parameter 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 0%, so the description must compensate for all 10 params. It names the input families (MRR, customers, churn, CAC, margin, growth), which maps loosely to cac/churned_mrr/gross_margin_pct/new_mrr, but leaves prior_mrr, expansion_mrr, new_customers, and sales_marketing_spend unexplained and gives no units (dollars vs. percentage for gross_margin_pct).

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

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

States a concrete verb-and-resource pair: take MRR/customer inputs and compute a specific named set of SaaS metrics (ARR, ARPA, LTV, CAC, payback, Rule-of-40, NRR, GRR) plus a grade and a ranked fix list. Nothing else in the sibling list does anything similar, 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?

Tells the agent exactly what to supply ('POST your MRR/customers') and flags that churn/CAC/margin/growth are optional, which frames the required-vs-optional call. It gives no when-not-to-use conditions or pointer to an alternative, but no sibling tool overlaps this computation.

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?

No annotations are present, so the description carries the burden and does disclose key traits: the 1-24 sprint limit, that it is 'pure math + advisory, no LLM' (no side effects or external calls), and the shape of results including health tags and an overall grade. It omits auth/rate-limit/permission details and whether it persists anything, which keeps 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?

Front-loaded with the core action and the input contract, and every clause maps to a real output or constraint. It is dense and slightly run-on, 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 3-param, nested-array tool with no output schema and no annotations, the description covers the input semantics and fully summarizes the return payload (metrics list, health tags, overall grade, ranked focus list). The only meaningful omission is guidance on team_size and a note on how many sprints are needed for trend/stability to be meaningful.

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

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

Schema coverage is 67%; the description adds meaning by explaining that the array holds committed/completed points plus optional per-ticket estimate-vs-actual data and by tying estimate-accuracy output to that optional ticket data. team_size is still undocumented in both description and schema, leaving a gap.

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 ('POST 1-24 sprints ... get computed metrics') and enumerates exactly what is returned (velocity, commitment reliability, spillover, scope change, estimate accuracy, WIP concentration, grade, focus list). An agent can distinguish this aggregate health-advisory tool from point-focused siblings like estimate_sanity or commit_hygiene without opening the schema.

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

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

The description conveys the input contract and output shape but never says when to prefer this tool over related siblings (estimate_sanity, commit_hygiene, coverage_check) nor states exclusions. Usage is implied by the 'sprint/delivery health advisor' framing rather than explicitly routed.

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 no annotations, the description carries the full load and does well: it discloses determinism ("no LLM"), that no house rates or milestone conventions are hardcoded, that all team checks default off, the 50-story batch cap, and that "missing fields ARE findings." The remaining gap is return-value shape — no output schema exists and the description never says what a finding looks like.

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 sibling disambiguation, then the optional-config switch, then limits. The long parenthetical enumeration of team-specific checks is dense but each item maps to a real config field, so it earns its space; it could be split into shorter sentences for scannability.

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 3-parameter tool with heavy nesting and no output schema, the description covers modes, limits, and scoping well. The one missing piece is the shape of the lint findings, which an agent would need to interpret results since no output schema documents 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 baseline is 3, but the description adds real semantic value: it explains that rate_config is optional and that omitting it disables all team-specific checks, and it names the five check families the nested config unlocks. It adds the cross-batch evaluation rule for dependencies and companion types.

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

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

States a specific verb+resource ("deterministic structural quality linter for user stories") and enumerates the exact concepts checked (narrative completeness, acceptance criteria, dependency IDs, CRUD split, pagination). It explicitly positions itself relative to the sibling ticket_lint, so an agent can distinguish the two 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?

Clearly signals two modes: omit rate_config and only universal checks run, or supply it for team-specific checks. It also states batch max of 50 and that dependency/companion checks are cross-batch. It does not address overlap with other quality siblings like acceptance_criteria_validator or dependency_check, leaving the routing decision partly implicit.

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?

No annotations are present, so the description carries the full behavioral burden. It discloses the return shape (findings with severity and remediation) but says nothing about whether the scan is read-only, what data leaves the environment, how the archive inputs interact with the zero-required-parameter signature, or what happens if no input is supplied.

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

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

Three short, front-loaded sentences with the resource scope stated first and the return value last. The middle sentence is a positioning claim rather than operational information, but it is brief and does aid selection.

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 scanner with no annotations and no output schema, the definition covers purpose and rough return content but leaves important gaps: what is scanned when no parameters are supplied (all params optional), and how archive_url and archive_base64 relate to each other. Adequate but incomplete.

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 all three parameters (ecosystems, archive_url, archive_base64) are already documented in the schema. The description adds no syntax, precedence (archive_url vs archive_base64), or format detail beyond that, 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 (scan) and concrete resource set (package manifests, lockfiles, MCP server configs) targeting supply-chain compromises, and claims a distinctive scope (MCP config as a security surface). It does not explicitly distinguish itself from the sibling dependency_check, so it stops short of a 5.

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

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

The stated scope implies when the tool applies (auditing manifests/lockfiles/MCP configs for compromises), but there is no explicit when-to-use/when-not guidance and no mention of dependency_check as the nearest alternative. Routing 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?

No annotations are provided, so the description carries the full burden and does so: deterministic/no-LLM behavior, the 50-ticket batch cap, type-aware rules, an optional strict profile, and the per-ticket severity+fix output shape. This is unusually complete disclosure for an unannotated 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?

Front-loaded with the purpose and sibling exclusion, then the actionable payload. The middle run-on list of rule categories is dense but each item adds real signal; nothing is filler.

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

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

With no output schema available, the description supplies the return contract (per-ticket findings with severity and concrete fixes, score, grade, ready/needs_work verdict, batch summary). For a nested-object, zero-required-param tool this leaves nothing material unexplained.

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

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

Schema coverage is 67%, and the description compensates by explaining the batch cap, the singular-vs-plural alternatives, and that 'strict' is a stricter rule profile — semantics the bare enum doesn't convey. The 'missing fields ARE findings' nuance is also echoed, reinforcing the schema's own note.

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 ('Full Jira-ticket quality linter') plus explicit scope ('whole ticket, not just AC') and names the sibling that handles the narrower job. The agent can distinguish it from acceptance_criteria_validator and story_lint 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?

Explicitly routes the AC-only case to acceptance_criteria_validator, and the batch-vs-single usage is stated ('POST one ticket or a batch (max 50)'). It stops short of stating when *not* to lint at all, but the primary sibling decision is resolved in the text.

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 no annotations, the description carries the full burden and does well: it discloses the matching mechanism (deterministic keyword matching, no LLM), the output's shape (ranked endpoints plus high/medium/low confidence), and that matching is scoped to the platform's own catalog. It omits operational traits an agent might care about, such as cost/rate limits (rate_call and buy_credits exist as siblings) or failure behavior on an unmatched task.

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 question and the POST/return contract in the first sentence, then the mechanism, then the sibling relationship. Dense but nearly every clause adds information; the nested parenthetical about model_advisor being recommendable is slightly convoluted and costs a reread.

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, so the description must convey return values, and it does at a high level (ranked endpoints, confidence label). For a 4-parameter, non-destructive lookup tool that is close to complete; the remaining gap is not naming the result fields or what an empty/low-confidence result looks like.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it explains that `context` is meant for a prior model_advisor rationale or extra detail that doesn't fit in `task`, and that the tool pairs with model_advisor so the parameter has a concrete source. `tools` and `top_n` are left to the schema, which already documents them.

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 question the tool answers ('Which QL-API endpoint fits this task') and then states the action and return: POST a task description, get ranked endpoints with confidence labels. It explicitly differentiates itself from model_advisor and explains that model_advisor is itself in the recommendable catalog, so an agent can tell the two apart without reading 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 concrete invocation guidance — 'call them independently and chain the results yourself' — and names the optional `context` hand-off from model_advisor. It stops short of stating when this tool should NOT be used (e.g. when the caller already knows the endpoint, or in what order advice tools should be tried when both are relevant).

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 no annotations, the description carries the full behavioral burden and discloses important traits: 5MB size limit, one-day auto-expiry, key-only readability, auth requirement, and no billing. It does not specify URL TTL or failure behavior for oversized uploads, but the main constraints are covered.

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

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

The description is front-loaded with the core action and immediately explains the two-step handoff and constraints. Every sentence contributes operational or behavioral detail without wasteful 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?

For a presigned-upload helper with no output schema and no annotations, the description supplies the return values (URL and upload_id), the follow-up flow, key limits, expiry, auth, and billing context. An agent has enough information to invoke it and use 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?

The schema has 100% description coverage for the single content_type parameter, including examples and the default. The description adds no parameter-specific semantics beyond what the schema already provides, so the 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?

The description states a specific verb and resource: get a presigned S3 PUT URL for uploading a file. It also identifies the upload_id handoff to a consuming endpoint, so the tool's role is unambiguous among unrelated 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?

It gives a clear operational flow: call this tool, PUT the file to the returned URL, then pass upload_id to the consuming endpoint. It does not explicitly name when not to use it or alternatives, but no sibling appears to overlap with this upload capability.

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 no annotations, the description carries the burden and does so well: it enumerates the exact checks, declares determinism ('caller supplies the reference date - fully deterministic, no LLM'), and states a policy stance ('never suggests inflating hours'). It does not explicitly state that the tool is side-effect-free/non-mutating, which would close the last gap.

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?

Single dense paragraph, front-loaded with purpose followed by enumerated checks and return shape — every clause earns its place. It is long, but the length is justified by the check inventory.

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 spells out the return contract (pass/warnings/blocked verdict, per-entry violations with fixes, hour totals by author and date). Determinism and entry cap (via schema) round it out; only the non-mutating guarantee is left implicit.

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 today, policy overrides, and the entries shape in detail. The description adds only the default rounding increment (0.25h) and the semantics of a few checks, which is marginal value over 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 ('run a batch of worklog entries through configurable guardrails') plus the operational scope ('BEFORE posting to a time-tracking system'). No sibling tool covers worklog validation, so it is trivially distinguishable from the lint/validator family.

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?

Clearly conveys the usage moment — pre-posting validation of timesheet entries — which tells an agent when this belongs in a workflow. It stops short of naming an alternative or exclusion, so it is not a full 5.

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