Fresh402 Agent Intelligence

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

No annotations are provided, and the description carries the full behavioral burden: it discloses the $0.005 USDC cost, x402 payment challenge behavior, no JavaScript execution, cache reuse still costing money, first URL check without prior state returning changed:null, 409 pending-batch replay, and trial-capacity 429s. It also states that exhaustion never authorizes a charge and that ordinary requests retain the paid challenge.

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

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

The core check semantics are front-loaded, but the description is a dense wall of text dominated by payment protocol routing, MPP receipt metadata, Circle Gateway recovery tokens, and trial enrollment details. Those details may be operationally relevant, yet they are repeated and interleaved rather than structured, so many sentences do not earn their place for simple tool selection and invocation.

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

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

For a complex paid tool with no output schema, the description is unusually complete: it covers payment prerequisites, cache behavior, first-check changed:null, watch reuse, no-JS execution, and key error states. It does not fully describe the result payload shape beyond changed:null and the compact diff, which keeps it from a 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description usefully reinforces the exactly-one-of url/watch_id rule and the rule that content fields are omitted with watch_id, but it does not add syntax or format meaning beyond what the schema already documents for selector, previous_hash, html_attributes, ignore_selectors, and ignore_json_paths.

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 opening sentence states a specific verb and resource: check whether public HTML, JSON, or text changed, with optional same-text link/attribute detection. It also scopes the tool as an on-demand freshness check with a compact diff, not background monitoring, and later names fresh402_register as the free watch-registration path. An agent can distinguish it from siblings 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 explicitly says to supply exactly one of url or watch_id, to omit all content-rule fields when watch_id is used, and to reuse returned watch_id/hash for later checks. It contrasts on-demand checks with background monitoring and names alternative payment routes (prepaid credits, MPP, Circle Gateway, free trial) with the condition for each. When-to-use and when-not-to-use are both present.

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 key traits: $0.01 USDC cost, required recovery-token handling, no partial success on provider failure, pending-finalization semantics for saved observations, retention windows, and 429 capacity behavior. It is dense and occasionally muddled, but behaviorally informative.

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

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

The purpose is front-loaded in the first sentence, but the remainder is a long wall of payment, prepaid, trial, and recovery boilerplate. Much of it is relevant to a paid tool, yet repetition and density hurt readability; a structured split into operation vs. payment semantics would be clearer.

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

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

For a complex paid tool with no annotations and no output schema, the description covers payment authorization, recovery tokens, trial credentials, retry behavior, and retention rules thoroughly. It stops short of describing the actual response shape, but the operational context an agent needs to invoke it correctly is largely present.

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

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

Schema description coverage is 100%, so each parameter is already well documented in the schema (e.g., slot and event_topics constraints, previous_snapshot ownership rules). The description adds only general framing ('explicitly selected storage/ABI', 'bounded selected events') without new syntax or format detail.

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 opening sentence names a specific verb ('Observe') and enumerates concrete resources (code, proxy slots, getters, selected storage/ABI, bounded events) at a finalized Base address, plus optional snapshot comparison. An agent can tell this is a contract-inspection tool, though the description does not explicitly differentiate it from siblings like fresh402_token_facts or fresh402_smart_diff.

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

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

The description gives extensive operational context about payment, recovery, and trial usage, but never states when to choose this tool over contract_diff, token_facts, or wallet_watch. Usage is implied by the observation scope rather than routed explicitly.

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 does so extensively: it discloses one-fetch/JSON-parse behavior, output and work limits, 422 failures for missing JSON fields, 409 batch replay behavior, payment/auth requirements, prepaid and trial constraints, and prohibited credential combinations.

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 first sentence is well front-loaded, but the description then balloons into long payment, prepaid, MPP, Circle Gateway, trial and documentation instructions. Much of this is operational payment material rather than extraction-tool selection or invocation guidance, making the definition poorly sized.

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

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

There is no output schema, but the description names the returned artifacts such as text, metadata, headings, links, structured_data and feed projection fields, and it explains major constraints and payment paths. It could still specify the exact response shape more precisely, but it is complete enough 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?

Schema description coverage is 100%, so all 10 parameters are already well documented in the input schema. The description restates some semantics such as feed_mode, json_pointer/json_pointers mutual exclusion, max_chars clipping and CSS noise exclusions, but adds little beyond the detailed schema.

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

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

The opening sentence states a specific verb and resources: extracting readable text, metadata, headings, links and JSON-LD from one public HTTPS document. It also distinguishes this tool from watch/registration workflows and from JavaScript rendering, crawling or version comparison.

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 says to use this tool for static HTML, JSON or plain text, and notes that no watch or prior registration is needed. It also rules out feed crawling, background subscriptions, JavaScript rendering and version comparison, though it does not explicitly name sibling alternatives such as the diff or watch 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 discloses substantial behavioral detail: bounded analysis limits (256000 decoded bytes, 100 paths, 500 operations), unsupported inputs (YAML, external reference fetching, API-operation execution), error behavior (404 for unavailable hashes, 409 pending batches, 429 capacity), and payment/auth requirements. It also clearly states the tool does not provide a general satisfiability or compatibility proof. The payment details are excessive but they do transparently disclose invocation requirements.

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 far too long for the tool: after a clear purpose statement, it devolves into extensive payment, prepaid, MPP, Circle Gateway, trial, and cross-reference material. Much of this is irrelevant to selecting or invoking fresh402_openapi_contract_diff and drowns the core usage guidance. The purpose is front-loaded, but overall the text is bloated and repetitive.

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?

It covers prerequisites, limits, unsupported cases, auth/payment options, and some error modes, which is substantial for a complex tool. However, there is no output schema and the description does not explain the shape or fields of the returned compatibility evidence, so an agent still lacks guidance on interpreting results. Payment coverage is disproportionately detailed while result semantics remain vague.

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 watch_id, compare_to, and previous_hash are already fully documented in the schema. The description adds a concise restatement that compare_to accepts previous or baseline and that previous_hash overrides it, but this does not go meaningfully beyond the schema. Baseline 3 is appropriate when structured fields do 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?

The opening sentence names a specific operation (compatibility evidence detection) on a specific resource (public JSON OpenAPI 3.0/3.1 contracts) and enumerates the compared aspects: paths/methods, required fields, scalar domains, and auth alternatives/scopes. It also distinguishes itself from fresh402_smart_diff explicitly. The purpose is clear, though the jargon-heavy phrasing and surrounding payment text make it less immediately legible than a direct verb such as 'compare'.

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

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

It states 'Use for API contract review' and contrasts that with fresh402_smart_diff for general documents. It also gives the prerequisite workflow: register the contract URL first with fresh402_register, then reuse watch_id. It does not explain when to use this versus fresh402_contract_watch or fresh402_check, but the primary usage context and one alternative are 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 idempotency (repeating returns existing state without fetching or refreshing), cost ($0, quota-bound, no x402 payment client), and limits (no JS execution, no background monitoring, stores a reference point only). The cost/auth story is repeated in a later sentence rather than consolidated, which costs it a point.

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 correctly with the core verb and scope, but the tail is padded: 'Registration is free ($0), subject to quotas, and requires no x402 payment client' and 'Free baseline registration needs no trial key, wallet or payment' say the same thing, and 'stores a reference point, not continuous monitoring' overlaps with 'no background monitoring.' The trial-endpoint sentence is useful but drifts from the tool's job.

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

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

Covers the operational facts an agent needs for a 5-parameter creation tool with no output schema: idempotency, cost, quotas, watch identity, and the OpenAPI special case ('register the JSON contract without any content rules'). It never sketches the returned watch_id/hash payload, though the schema description does reference it.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining that url plus rules jointly identify the watch and that changing rules yields a different watch, which is a semantic not visible from the schema fields. It also notes html_attributes is opt-in and that watch identity must come from the actual returned ID.

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?

First sentence names a specific verb-plus-resource (create or retrieve a free persistent baseline) and the supported content types. It explicitly positions itself relative to siblings (Smart Diff, OpenAPI Contract Diff, Check), so an agent can distinguish it without opening another 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?

States when to call it (before Smart Diff or Contract Diff, or to obtain a reusable watch_id/hash), and gives an explicit alternative path: 'Check also accepts url directly and can create its watch during the paid call.' It also names the free-comparison allowance route via the trial endpoints.

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 and does so extensively. It discloses limits such as up to 200 content changes, no LLM or JavaScript rendering, legacy HTML text-only fidelity, array identity behavior, payment challenge conditions, idempotency requirements, and possible 409/429 responses.

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

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

The core purpose and usage guidance are front-loaded, which is good. However, the description is very long and spends substantial space on payment-provider, prepaid, MPP, Circle Gateway, and trial boilerplate that could be moved to linked docs; many sentences are operationally relevant but the overall structure is manual-like rather than concise.

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

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

Given the tool complexity, four parameters, rich schema, and no output schema, the description is complete enough for an agent to understand what the tool returns conceptually and what conditions affect execution. It covers comparison modes, identity rules, limits, fidelity caveats, payment requirements, and recovery/error behavior.

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

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

Schema description coverage is 100%, so the baseline is 3; however, the description adds operational meaning by explaining compare_to modes, how previous_hash overrides them, and that json_array_keys rules affect only the comparison and not the watch/hash. Much of the parameter detail is already in the schema, so it does not reach 5.

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 opening sentence states a specific verb and resource: it explains structured changes in a registered public document, covering JSON Pointer changes, HTML block changes, and significance hints. It also explicitly tells the agent to use it instead of Check when a simple changed/unchanged flag or short text diff is insufficient, distinguishing it from the sibling tool.

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

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

The description gives explicit usage conditions: use instead of Check when the output needed is richer than a flag or short diff; first obtain watch_id with free fresh402_register; compare_to defaults to previous or can be baseline; previous_hash overrides compare_to. It also says to omit new options for existing index/text behavior, which is actionable 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?

With no annotations, the description carries the full behavioral burden and discloses extensive traits: paid $0.010000 USDC per call, required recovery token handling for x402/MPP, idempotency key requirements, provider failure not becoming paid success, pending finalization semantics, and retention periods. It also explains trial versus paid credentials and 429 behavior. These details go well beyond the schema and are highly relevant to correct invocation.

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 front-loads the core purpose well, but then expands into a very long block of payment, prepaid, recovery-token, trial, and legal retention details. Much of this is operational and some is necessary, but the overall text is far too dense and not well structured for an agent to scan quickly. The volume exceeds what is needed to select and invoke the 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?

Given no annotations, no output schema, and a complex paid/recovery workflow, the description is largely complete on invocation behavior: payment model, auth headers, recovery token persistence, error semantics, and trial rules. It does not describe the returned token-facts structure or meaning of fields, which leaves some gaps because no output schema exists. Still, the critical behavioral context is present.

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

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

Schema description coverage is 100%, so the schema itself fully documents chain_id, address, block, and categories. The description only broadly references 'contract-reported token identity, metadata, supply and limited control facts' and does not add parameter-specific syntax, defaults, or edge cases beyond the schema. Baseline 3 is appropriate 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?

The opening sentence states a specific verb and resource: read contract-reported token identity, metadata, supply, and limited control facts at one pinned finalized Base block. It also clearly excludes safety scoring, honeypot simulation, and verified-source claims, helping distinguish it from safety-check tools. However, it does not name or contrast with any sibling tool explicitly.

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 through phrases like 'No safety score, honeypot/trading simulation, verified-source claim' and provides payment/trial operational context. But it never explicitly says when to choose this tool over fresh402_check or other siblings, nor does it name alternatives for the excluded safety-assessment use case. The practical usage guidance is therefore 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 so thoroughly: cost ($0.02 USDC on Base), cursor ownership semantics, required recovery token and its transport for REST vs MCP, idempotency rules, the rule that provider failure/partial scan never becomes a paid success, and what observation_saved=false plus persistence_error means (do not use returned IDs, retry recovery only). Retention windows and 429 capacity behavior are also disclosed.

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

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

The purpose is front-loaded, but the body is a ~250-word run-on mixing payment plan terms, trial credentials, tariff grants, and legacy web package language, much of which does not change tool selection or invocation. Sentences like 'Historical web package terms remain unchanged' do not earn their place.

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

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

For an 8-parameter paid read with no output schema, the definition covers the important unknowns: pagination via cursor, bounded finalized pages, gap failure, has_more semantics, error/pending states, and cost. It stops short of describing the actual snapshot payload shape, but the flags and ID caveats it does surface cover the risky parts.

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 is already documented in the schema; the baseline of 3 applies. The description adds a little beyond the schema — that the cursor must be persisted and that the next page requires a new paid operation — but contributes no field-level semantics the schema lacks.

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 opening sentence gives a specific verb (Read) and precise resource (ETH balance snapshots and selected ERC-20 Transfer events for one wallet, bounded finalized page), and explicitly excludes what it is not (full native/internal/NFT/transaction history). It distinguishes scope well, though it never names a sibling tool to steer against.

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 concrete operational guidance — persist the cursor, use a new paid operation for the next page, use an approved payment client, accept /v3/prepaid/all-services terms before purchase, and there is an optional free trial path. However, it never states when an agent should pick this over fresh402_contract_watch or fresh402_token_facts, so sibling selection 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.