SqueezeOS — Institutional AI Market Intelligence

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

Beyond the annotations, the description discloses a critical behavioral trait: payment_response is forwarded as PAYMENT-SIGNATURE and 'SML never signs or spends.' This gives the agent important trust and side-effect context that annotations alone do not convey, though it stops short of detailing failure modes or response behavior.

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

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

Two tightly written sentences with no redundancy. The core action is front-loaded, and the important 'SML never signs or spends' caveat is placed immediately after the parameter behavior it qualifies.

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

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

For a tool with only two parameters and no output schema, the description covers the main invocation behavior and the key security property. It lacks explicit return or error semantics and does not describe what happens on failure, but it is otherwise sufficient for an agent to understand the operation's purpose and primary 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 description coverage is 0%, so the description must compensate. It does clarify that payment_response is the caller-supplied x402 authorization forwarded as PAYMENT-SIGNATURE, and job_id is implicitly the job to retry. However, job_id semantics are only lightly covered and no additional constraints or usage details are provided.

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 action ('Retry') and resource ('one immutable job') and introduces the key mechanism (caller-supplied x402 authorization). This clearly distinguishes it from sibling tools like aftersearch_quote or aftersearch_resolve, which serve different purposes.

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 the tool is used to retry a job with a payment authorization provided by the caller, but it does not explicitly state when to use it versus alternatives or mention prerequisites like obtaining a quote first. Usage is inferable but not fully spelled out.

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

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

Annotations already provide readOnly, idempotent, openWorld, and non-destructive facts. The description adds useful context by saying the terms are 'fresh,' scoping the operation to 'one immutable job,' and clarifying that a 402 is not an actual payment. It does not contradict the annotations.

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

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

The description is two sentences and every word earns its place: the core action is front-loaded and the second sentence adds a high-value definitional clarification. There is no restatement of the title 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?

For a one-parameter read-only quote tool, the description conveys the purpose, the input scope, and the critical 402 semantics, and the annotations cover side effects. The only notable gap is that with no output schema the exact structure of the quoted terms is not described, but that is minor given the tool's simplicity.

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 one required job_id with a hex pattern but 0% description coverage, so the description must explain the parameter. It never names job_id and only says 'one immutable job,' which provides minimal semantic context. Format, source, and relationship to the job are left entirely to the schema's bare pattern.

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 action and object: 'Return fresh x402 PAYMENT-REQUIRED terms for one immutable job.' This clearly distinguishes quote from payment-acceptance siblings like aftersearch_accept, and the clarifying sentence 'A 402 is not payment' reinforces the resource semantics.

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 intended use is implied — call this to obtain current payment terms before acting on a 402 — but there is no explicit when-to-use statement, no mention of prerequisites, and no comparison to alternative tools such as aftersearch_accept or aftersearch_resolve. The guidance is enough to infer context but leaves the selection boundary 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the specific claim 'never spends' and notes that the output includes an 'immutable job' and 'bounded Evidence Pack', which are useful behavioral hints, but it does not disclose other aspects such as error behavior or performance limits. It adds some value beyond annotations but not extensively.

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 concise sentence with no filler, and it leads with the action verb. It packs a lot of information but is dense and could be more readable; however, it is appropriately sized for a simple tool.

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

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

There is no output schema, so the description should explain what the tool returns. It lists the outputs (intent, Evidence Pack, job, quote pointer) but does not explain their structure, how they are returned, or any error conditions. Given the tool's complexity and lack of structured output documentation, the description is insufficient for an agent to fully understand the result.

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

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

The schema describes a single 'query' parameter with maxLength 60000, but no description. The tool description only refers to 'a query' generically and does not elaborate on format, content, or examples, so it adds no meaningful semantic information for the parameter. With 0% schema coverage, the description fails to compensate.

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 action ('Compile a query') and lists concrete outputs (intent, Evidence Pack, job, quote pointer), but it uses domain jargon without plain-language clarification, making it less accessible than ideal. It distinguishes from siblings by implying a read-only compilation step, but does not explicitly contrast with any sibling.

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

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

There is no mention of when to use this tool versus alternatives, no exclusions, and no reference to sibling tools. An agent has no guidance on selecting this over aftersearch_accept or aftersearch_quote.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive; the description adds that the tool produces a classification ('confirm, contradict or missing') and attaches sources, plus that URLs must be public. This extra behavioral/return context is useful and doesn't conflict with the annotations.

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

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

The description is a single compact sentence that front-loads the verb, scopes the input, and states the output. No redundant phrases or restating 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?

For a one-parameter tool with no output schema and safety hints covered by annotations, the description covers the essential invocation details: what to pass and what to expect back. It is slightly thin on what 'sources' means or how contradictory evidence is presented, but that does not block correct usage.

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 schema coverage at 0%, the description does the semantic work for the single parameter: it specifies that serp_text_or_url can hold pasted SERP/AI text or exactly one caller-provided public URL. This clarifies the accepted formats beyond the bare parameter name and length constraints.

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 ('Verify') and identifies the exact resource: pasted SERP/AI text or a caller-provided public URL. It also defines the return semantics (confirm/contradict/missing with sources), which distinguishes it from sibling aftersearch actions like accept/quote/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?

It clearly tells an agent when to invoke it: whenever there is pasted SERP/AI text or a single public URL that needs verification. It does not, however, list alternative tools or exclusion criteria, so it stops at clear context without when-not guidance.

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

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

The description adds valuable behavior beyond the annotations: an unsigned call never auto-spends and returns a live x402 PAYMENT-REQUIRED challenge, and retry requires a challenge-bound signature. It also clarifies authentication requirements by stating no separate account/API key is needed. This does not contradict the annotations.

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

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

The description is compact—two sentences—and front-loads the tool's purpose before covering prerequisites and the payment flow. Every sentence adds actionable information without repetition or 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?

For a tool with no output schema, the description adequately explains the expected return format (Markdown), the input constraint (publicHTTPS URL), and the x402 payment flow. A small gap is that max_chars behavior is not mentioned in the description, but the challenge flow is covered well enough for an agent to invoke the tool correctly.

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

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

The description reinforces the url and payment_signature semantics beyond the schema, especially the challenge-bound nature of the payment signature. However, the optional max_chars parameter has no descriptive content in either the schema or the tool description, so its semantic remain under-explained.

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

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

The description clearly states a specific action: give one public HTTPS URL and receive compact LLM-ready Markdown via the Clean Web Reader service. It clearly distinguishes itself from the sibling capability and x402 tools, none of which perform direct URL-to-Markdown conversion.

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

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

The description gives concrete usage context: a publicHTTPS URL is required, no account/API key is needed, and an unsigned call returns a payment challenge that should be retried only with a challenge-specific payment_signature. It does not explicitly name when-not-to-use or alternatives, but the context is clear enough.

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

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

The description adds substantial behavior beyond the annotations: it explains the 402/payment flow, the requirement for confirm_write on POST, the preservation of PAYMENT-REQUIRED, and the non-exposure of sensitive routes or arbitrary auth headers. No contradiction with annotations exists.

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

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

The description is compact and densely informative, front-loading the core action and then covering the key behavioral rules in four sentences. Every sentence earns its place with no fluff or repetition.

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

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

For a tool with no output schema, the description covers the essential invocation flow, payment edge case, retry condition, and security restrictions. It is sufficient for an agent to decide when to call it, how to call it safely, and what to expect on 402 responses.

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

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

With schema coverage at only 43%, the description compensates well by explaining the relationship between method, confirm_write, and payment_signature, plus the role of alternative_intent in selecting the closest no-spend alternative. It adds meaning beyond the raw schema, though body and query parameters remain somewhat generic.

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

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

The description clearly states the tool calls a concrete SqueezeOS REST path on the canonical public host, which distinguishes it from sibling tools that discover, inspect, or compare capabilities. It also specifies the resource type and constraints like path format and excluded sensitive routes.

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

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

It gives clear method-level guidance: GET is read-only, POST requires confirm_write=true, and retry only with a challenge-specific payment_signature. It also states when the tool returns an alternative rather than the original result, though it does not explicitly name sibling tools as alternatives.

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

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

Annotations already cover the read-only, idempotent, non-destructive safety profile. The description adds meaningful behavioral context beyond that: the manifest is generated dynamically from the running Flask route table and represents the canonical product inventory, which tells the agent the data is live and authoritative.

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 no filler. The primary action is front-loaded, and the second sentence adds authoritative context without redundancy.

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

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

For a parameterless read-only tool with rich annotations and clear sibling context, this description fully covers what the tool does, where the data comes from, and why it matters. No critical call-time information is missing.

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

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

The tool takes zero parameters, so there are no parameter semantics to clarify. The description correctly implies a no-argument call that returns the full manifest, and the schema is already complete.

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

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

The description names a specific verb ('Return') and a specific resource ('current machine capability manifest generated from the running Flask route table'). It also defines the tool's role as the 'canonical product-inventory authority for MCP discovery,' which clearly distinguishes it from sibling tools like inspect_capability or discover_capabilities.

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

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

The description gives clear context: this is the canonical authority for capability inventory, so an agent can recognize it as the go-to source for a complete machine capability list. However, it does not explicitly state when not to use it or name alternatives with selection criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: it operates on live metadata, produces no fabricated composite score, and is bounded to 2-5 capabilities. There is no contradiction with annotations.

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

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

A single sentence that front-loads the action and scope, then adds a valuable limitation. Every part of the sentence contributes meaning without redundancy.

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

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

There is no output schema, so the description should clarify return expectations; pointing to 'the same real metadata returned by inspect_capability' helps, but the 'probe' parameter remains unexplained. Overall, it is mostly sufficient for a read-only comparison tool but has notable gaps.

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

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

Schema description coverage is 0%, so the description must carry parameter explanation, but it only clarifies the count range (2-5). It does not explain the 'probe' boolean or give explicit meaning for 'sml_ids' beyond what the name implies, leaving a real semantic 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 ('Compare') and resource ('2-5 live capabilities'), and distinguishes this tool from inspect_capability by noting it uses the same real metadata rather than a fabricated composite score. The purpose is immediately clear and well differentiated from siblings.

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

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

Clearly implies when to use: when comparing multiple capabilities' real metadata rather than inspecting a single capability. It references inspect_capability and explicitly excludes fabricated composite scoring, but it does not explicitly list alternative tools or state 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?

Annotations cover the read-only, idempotent, open-world safety profile, so the description isn't burdened with restating that. It adds a valuable behavioral promise: 'without fabricating scores' – implying the tool returns only evidence-backed results, which is not disclosed elsewhere. This goes beyond the annotations and gives an agent confidence about data integrity.

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

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

Two sentences carry zero waste. The purpose is front-loaded, and the mode distinction follows naturally. Each sentence earns its place with concrete information, achieving high information density without bloat.

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

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

The description is adequate for a search tool with three obvious parameters, and annotations cover safety. However, it does not mention what the response looks like (e.g., list of capability names, metadata, sorting), which an agent might need to interpret results. Since there is no output schema, this is a gap, but the tool's name and sibling context partially compensate.

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 illuminate the parameters. It explains the 'mode' parameter well, distinguishing lexical from unified and noting the no-fabrication guarantee. The other parameters (query, limit) are self-explanatory from their names and constraints, so no extra detail is necessary. The explanation of mode fully compensates for its complexity.

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: 'Search the live SqueezeOS capability inventory.' It clearly distinguishes this from sibling tools like inspect_capability (which likely targets a specific capability) and call_capability (which invokes). The mention of two modes further clarifies scope.

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 guidance on when to use lexical vs unified mode ('Lexical mode is always available; unified mode may add configured evidence-backed semantic/graph context'), but gives no explicit direction on when to choose this tool over its siblings (e.g., inspect_capability, recommend_capability). The purpose implies search usage, but no exclusions or alternatives are named.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds valuable context by explaining that it returns real metadata and may perform a real liveness probe when safe, and explicitly disclaims invented reliability scores. No contradiction with annotations.

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

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

The description is a single front-loaded sentence that efficiently communicates the core purpose and key behavioral nuance. No filler or repetition.

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

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

The description gives a solid overview of the tool's purpose and return content (endpoint, payment metadata, liveness probe), which is adequate for a simple read operation given the rich annotations. However, the 'when safe' condition and the meaning of the 'probe' parameter are left undefined, and there is no output schema to compensate.

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 explain parameters. It contextualizes sml_id as the capability identifier, but it never mentions the 'probe' boolean parameter, its default, or how it affects behavior. This is a significant 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?

The description clearly identifies the action ('Inspect'), the resource ('one live capability'), and the required key ('sml_id'). It also distinguishes itself from tools that produce reliability scores by emphasizing real liveness probes, though it does not explicitly name 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 description implies when to use the tool: when you need to inspect a specific capability by sml_id and get real endpoint/payment metadata. However, it does not explicitly state when not to use it or which sibling tool to prefer 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?

Annotations already establish read-only, idempotent, non-destructive behavior; the description adds beyond this by promising live metadata and next actions, signaling dynamic or current data. It does not fully explain external-fetch behavior or output variability, but with strong annotation coverage, this is a reasonable level of disclosure.

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?

A single, front-loaded sentence states the core function first and then adds two specific output categories. Every phrase contributes meaning, and there is no repetition of the title or wasted words.

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

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

With no output schema, the description gives some return details but leaves the structure and ranking of results vague. It also lacks any guidance on how this relates to sibling tools, so an agent must infer when this is the right recommendation vs. discovery/comparison 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 descriptions are absent (0% coverage), so the description must compensate. It adds meaning to the required 'query' parameter by defining it as a natural-language need, but it never explains the optional 'limit' parameter beyond what its name/default already imply.

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

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

The description names a specific operation—returning best-matching real SqueezeOS capabilities for a natural-language need—with unique output elements (live endpoint/payment metadata, next actions). This distinguishes it from sibling tools like discover_capabilities or inspect_capability without requiring schema inspection.

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 natural-language need' gives a clear usage context, implying this is the tool to choose when the user expresses intent in plain language. However, it does not explicitly say when not to use it or name alternatives such as discover_capabilities or compare_capabilities.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive traits. The description adds the useful behavioral trait that results are raw and not synthesized into cluster-health or synchronization claims, which is beyond the annotations. It does not describe response shape, but for a no-parameter status endpoint this is minor.

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?

A single sentence contains the verb, resource, and the critical trust boundary. Every word earns its place and the main action is front-loaded.

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

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

For a no-parameter, read-only status tool with rich annotations, the description is nearly complete. The only minor gap is that it doesn't hint at the shape or granularity of returned data, but the raw-endpoint framing plus the non-synthesis caveat gives sufficient context for invocation.

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

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

There are zero parameters and schema coverage is complete, so the schema has nothing left to document. The no-parameter baseline of 4 applies; the description doesn't need to add parameter meaning.

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

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

The description names a specific verb ('Read'), a resource ('live SqueezeOS status endpoint'), and a scope-limiting caveat ('does not synthesize cluster-health or synchronization claims'). This makes the tool's purpose exact and separates it from any capability/x402 siblings that might appear related.

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 establishes the intended use: reading live status rather than relying on synthesized health/sync assertions. It doesn't name alternative sibling tools or provide explicit when-not-to-use conditions, but the non-synthesis caveat gives a concrete boundary.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior, so the bar is lower. The description adds a crucial behavioral caveat: the returned contract is canonical for discovery only, and exact spend terms must come from the target resource's fresh challenge. This gives agents an important expectation about the data's authority without contradicting any annotations.

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

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

The description is two sentences with no filler: the first identifies the action and resource, the second provides the key caveat about spend-term authority. Every sentence earns its place and the most important information is front-loaded.

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

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

For a simple, parameterless, read-only tool with strong annotations, the description is nearly complete. It identifies the returned object and flags the important limitation about exact spend terms. It could go slightly further by explaining how the discovery contract relates to x402_evidence or x402_readiness, but it is sufficient for correct invocation.

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

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

The tool has zero parameters and an empty input schema, so there is no parameter semantics for the description to add. Per the baseline for parameterless tools, this receives a 4 because the description does not need to explain what is already absent.

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 action ('Return') and a specific resource ('the canonical SqueezeOS x402 v2 discovery contract'), which is clearly distinguishable from siblings like x402_evidence and x402_readiness. It also adds the scope-limiting caveat that exact spend terms are not authoritative here. This gives an agent an unambiguous understanding of what the tool 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 makes clear the tool returns the discovery contract and warns that it should not be treated as the source of exact spend terms, since those come from a fresh PAYMENT-REQUIRED challenge. It does not explicitly name alternatives, but the intended usage and an important limitation are clearly stated. The guidance is mostly implicit rather than a full when-to-use/when-not-to-use comparison.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context about provenance ('canonical x402 rail') and the semantic rule that challenges/signatures are not valid proof, going beyond what the annotations convey.

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

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

Two tightly written sentences: the first front-loads the tool's purpose, and the second adds a distinct, important caution. There is no filler, repetition, or unnecessary detail.

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 no-input, read-only tool, the description is largely complete: it names the resource, the action, and a key interpretative rule. It does not describe the structure of the returned evidence, but with no output schema and no parameters, that is a minor gap rather than a critical omission.

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

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

The input schema has zero parameters and is fully covered, so there is no parameter ambiguity for the description to resolve. The baseline for a no-parameter tool applies, and the description appropriately does not invent unnecessary parameter details.

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: 'Read real settlement evidence recorded by the canonical x402 rail.' The caveat about challenge or signature not being proof further clarifies that this tool is the authoritative evidence source, distinguishing it from related x402 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 description clearly indicates that this tool is for retrieving real settlement evidence. The warning that a challenge or signature alone is never treated as revenue/settlement proof provides implicit when-not-to-use guidance, though it does not explicitly name sibling alternatives.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds the useful behavioral nuance that the surface is 'live' and 'canonical,' implying fresh, authoritative data. No contradiction; it just omits deeper details that are unnecessary for this simple read operation.

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?

A single sentence with no filler. The verb and resource are front-loaded, and the usage condition is appended economically at the end.

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

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

For a zero-parameter, read-only readiness check with rich annotations, the description covers what the tool does, when to use it, and the nature of the operation. No output schema exists, but none is needed at this level of complexity.

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

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

The input schema has zero parameters and full schema description coverage, so the baseline is 4. The description correctly implies there is no input to configure, and no additional parameter meaning is needed.

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

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

The description names a specific resource ('live canonical payment-rail readiness surface') with a concrete verb ('Read'), and the phrase 'before attempting a paid call' frames it as a pre-call gate. This clearly differentiates it from sibling tools like call_capability, x402_contract, and system_status.

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

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

The description explicitly states when to use the tool: before attempting a paid call. It does not mention when not to use it or name alternative tools, so it lacks the explicit exclusions needed for a 5, but the usage context is clear and actionable.

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