Tanod Agents

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on substantial extra behavior: typical latency (1-5s), gzipped payload, a USD 2 price with no free tier, a per-IP daily cap, and an explicit prompt-injection warning about untrusted endpoint data. That is genuinely valuable operational context beyond the 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, latency, and price, then the data-provenance caveat. Dense but each clause carries information; the security warning is slightly verbose but justified. No wasted 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, the description carries the return explanation ('Returns every current-snapshot record', gzipped) along with cost, latency, and rate-cap context. Complete enough to call it correctly, though the exact record shape is left unstated.

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 optional parameter, and the schema already documents it fully (100% coverage, 'Filter: exact source id'). The description restates that source restricts to one source, adding no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (download) and resource (full current-snapshot index, gzipped), and the 'full current snapshot' framing distinguishes it from the query-style siblings. However, it never names the sibling alternatives (query_agent_index, export_agent_index), so the agent must infer which one to pick.

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 (get the whole snapshot, optionally restricted by source) but gives no explicit when-to-use/when-not, no prerequisite conditions, and no routing to the obvious siblings query_agent_index or export_agent_index. An agent comparing tools gets no guidance on which to choose.

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 safety profile (readOnly, idempotent, non-destructive), and the description layers on genuinely new behavioral context: snapshot semantics ('current-snapshot records'), expected latency, mandatory pricing with no free tier, and a prompt-injection warning that endpoint names/urls/on-chain strings are untrusted data. The injection warning is safety-critical and not derivable from any structured field.

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, then inputs, then cost/latency, then safety — a sensible ordering with no filler sentences. It is dense but each clause carries distinct information, so nothing feels 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?

With zero required parameters, no output schema and full schema coverage, the agent has enough to invoke it correctly; the description supplies the return shape ('matching current-snapshot records'), cost and safety context. It stops short of describing record fields or any pagination/truncation behavior at the cap.

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 five parameters (including the 5,000 hard cap, the json/csv enum and the default null filters) are already documented in the schema. The description only restates them, adding the 'optional' framing but no new syntax or semantics.

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

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

States a specific verb+resource ('export a filtered slice of the index') and enumerates the filterable dimensions, so the agent knows what it retrieves. It never differentiates itself from the very similar siblings query_agent_index and bulk_agent_index, which is the remaining 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?

There is no explicit when-to-use or when-not-to-use statement and no sibling is named as an alternative. The pricing line ('USD 0.25; no free tier') and latency range implicitly tell the agent this is a paid export, which mildly informs a selection decision against free query siblings, but the agent must infer that.

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 read-only and idempotent annotations: latency, cost, free-quota terms, 404 non-charge behavior, and a security warning to treat returned strings as untrusted data. These details directly affect invocation planning and downstream handling.

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 inputs, then operational details and safety notes in a compact, well-ordered paragraph. Every sentence contributes actionable information.

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

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

With no output schema, the description still summarizes the return shape (record plus dated presence rows and price-change points). It also covers inputs, latency, pricing, quota, 404 handling, and data-trust caveats, making it complete for this read-only history tool.

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

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

Schema description coverage is 100%, and the schema already documents each of the three optional parameters. The description usefully consolidates the `source`+`id` versus `url` selection logic, but does not add syntax or constraints beyond what the schema provides, 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?

States a specific verb and resource: retrieval of presence and price history for ONE indexed record. The scope ('ONE indexed record') distinguishes it from bulk-query or scan siblings, so an agent can identify it without opening other tool definitions.

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 explains when the tool applies and how to identify the target record via `source`+`id` or `url`. It does not explicitly name alternative tools for bulk history or general agent-index queries, so it falls short of full when/when-not routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds a lot beyond them: typical latency (0.1-2 s), USD 0.02 price, 10 free queries per IP per UTC day, a has_more pagination signal, and an explicit warning to treat endpoint names/urls/on-chain strings as untrusted data. That trust and cost disclosure is exactly the extra context annotations cannot carry.

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

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

Every sentence earns its place and is front-loaded: purpose, then inputs, then returned record fields, then latency/cost/quota, ending with the data-trust caveat. It is dense but not padded.

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

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

Even without an output schema, the description names the returned fields (source, id, name, url, category, price_usd, network, first_seen, last_seen) and the has_more flag. For an 8-param all-optional read tool, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description restates the filter set but adds no syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description gives a specific verb and resource: 'query a daily cross-registry index of x402 endpoints and MCP servers.' This is clearly distinguishable from siblings like bulk_agent_index, export_agent_index, or scan_agent_package, so an agent can select 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?

It enumerates every filter (source, category, network, price range, q, paging), which implies how to narrow results, and it discloses the free-tier limit of 10 queries/IP/day. However, it never states when to prefer this tool over bulk_agent_index or export_agent_index, so routing 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?

No annotations are provided, so the description carries the full burden and does so thoroughly: nothing is installed, imported or run; sandbox unpacking as text; timing expectations (2-4s registry, 5-15s monorepo, 60s hard limit); timeout results still charged; 503/Retry-After queue sharing; pricing tiers; free-tier pool; version pinning for cache. It even warns that evidence strings are untrusted quoted data and that 'safe-looking' means no rule matched, not harmless.

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 invocation trigger, and nearly every sentence carries operative information (limits, caveats, pricing, caching). It is a dense single block rather than a structured list, which slightly hurts scannability for such a large volume of 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?

Given no annotations and no output schema, the description compensates fully — it even documents the return shape (verdict, risk_score, one-line summary, file:line findings) and enumerates the finding categories. An agent has everything needed to decide whether to call it and how to 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 description coverage is 100%, so the baseline is 3, but the description adds cost and behavior implications of parameter choices that the schema does not: a whole GitHub repo (no //subdir) or an upload >5 MB costs more, //subdir avoids monorepo timeouts, and uploads are never sent to OSV.dev.

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 security scan of an AI-agent skill (SKILL.md bundle) or MCP server package') and names the exact use moment ('before installing or enabling one'). It is unmistakably distinct from the sibling contract-scanning tools, which operate on a different domain entirely.

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

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

Explicit when: 'Call this before installing or enabling one.' It also supplies when-not/alternative guidance, e.g. scan a //subdir instead of a giant monorepo that would time out, and it defines the boundary of its own coverage (runtime-registered tools, downloaded code, nested archives, obfuscated logic).

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