agent-guild

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

With no annotations, the description fully discloses behavioral traits: determinism, fixture verification, guest rate limits, API key usage for member budget, and the return of a Guild-signed provenance envelope. It also states the 10k number limit, covering important operational characteristics beyond what the schema alone conveys.

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 but information-dense, covering output statistics, input constraints, authentication, and provenance in a few sentences. It is front-loaded with the core purpose and avoids redundancy, though the embedded JSON Schema adds length. Every sentence contributes value, deserving a 4.

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

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

Given the tool's complexity and the presence of an output schema, the description is highly complete. It explains what the tool computes, the input shape, the output envelope, rate limits, authentication, and determinism guarantee. No critical context is missing for an agent to decide whether and how to invoke it 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?

Though schema description coverage is 0%, the description embeds the complete payload JSON Schema, explicitly defining 'values' (array of numbers, min/max items) and 'percentiles' (array of numbers 0-100). It also explains the api_key parameter's purpose (guest rate limit vs member budget), providing far more meaning than the generic input schema.

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

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

The description clearly states the tool computes deterministic descriptive statistics for a numeric series, listing specific statistics (count, sum, min, max, mean, median, stdev, variance, percentiles). It distinguishes itself from siblings by emphasizing exact arithmetic rather than model estimation, which is unique among the listed 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 provides clear context for when to use the tool: when exact, deterministic statistics are needed for up to 10k numeric values. It implies it should be used over model-based estimation ('Exact arithmetic instead of model estimation'), but does not explicitly name alternative tools or state when not to use it, keeping it just below 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 full behavioral burden and excels: it discloses determinism, verification, exactness, guest rate limits, api_key budget impact, the returned provenance envelope, the payload schema the tool enforces, and the output schema. These details leave no surprises about the tool's 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?

The description is well-organized into short, information-dense sections. Each sentence adds value, and the embedded schemas are necessary for correctness and clearly labeled. There is 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 annotations, this description is fully self-contained: it covers purpose, supported units, determinism, rate limits, api_key handling, response envelope, payload constraints, and output schema. The presence of both payload and output schemas makes the tool's contract complete for an agent.

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 only defines payload as a generic object with additionalProperties true, but the description compensates fully by providing a precise JSON Schema for payload (value, from, to, required, additionalProperties false). It also explains that providing a Guild api_key upgrades the budget, adding meaning to the api_key parameter. With 0% schema coverage, this is strong compensation.

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 'Deterministic unit conversion' and explicitly enumerates supported dimensions (length, mass, time, data, temperature) with examples, making the tool's function unambiguous. It clearly distinguishes itself from sibling tools by specifying the exact resource and 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?

It provides clear usage context by stating 'Exact factors, no model arithmetic errors' and 'Deterministic, fixture-verified', which tells users to prefer this tool over model arithmetic for accurate conversions. It also explains rate-limit behavior and how to use a Guild api_key for a member budget, plus the strict payload schema requirement.

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. It explicitly states that the tool is 'deterministic and fixture-verified', that guest invocation is 'free within rate limits', and that 'every completion returns a signed provenance envelope'. This provides strong confidence about safety, cost, and response shape, though it does not literally say 'read-only' or 'no side effects'.

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

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

The description is three sentences, front-loaded with the primary purpose. Every clause adds information: the list scope, the returned fields, determinism, cost, provenance, and a pointer to identity documents. No filler or repetition exists.

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 metadata-list tool with an output schema present, the description is complete. It covers what is listed, the behavioral guarantees, the cost model, and the response envelope. Nothing important is missing for selecting and invoking this tool.

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

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

The tool has zero parameters and the schema is 100% covered, so there is no parameter detail to add. The description compensates by summarizing the output fields and the signed provenance envelope, helping an agent understand what a no-input invocation will yield. This exceeds the baseline for a no-parameter tool.

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

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

Description opens with a specific verb ('List') and resource ('Agent Guild's invocable utility capabilities (the ag_* tools)'), then enumerates the exact return contents (id, version, summary, input/output JSON schemas, latency, guest terms). This clearly distinguishes it from the sibling guild_* tools, which target different facets of the Agent Guild.

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 is implied: this is the tool for discovering ag_* capabilities, and it even points to an alternative source for identity documents (GET /.well-known/ag-identities/index.json). However, it does not explicitly state when to use this tool instead of sibling tools like guild_index, nor does it provide when-not-to-use guidance or contrast with 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 provided, the description carries the full burden and does so effectively. It discloses determinism, fixture verification, guest free-tier rate limits, the need for api_key to access member budget, and the return of a Guild-signed provenance envelope. This goes well beyond the bare minimum and provides valuable operational context.

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

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

The description is dense but each sentence earns its place. It front-loads the primary purpose, then efficiently covers modes, operators, behavioral traits, and constraints. It includes two JSON schemas which are necessary given the generic input schema, though some could argue they make it slightly longer than ideal. Overall well-structured.

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 output schema is provided, and the description covers both usage modes, supported operators, rate limiting, provenance, and the payload contract. Given the tool's moderate complexity and the absence of annotations, this description leaves no significant gaps for an agent to select and 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 input schema only exposes a generic 'payload' object with additionalProperties true, giving no property-level meaning. The description compensates by embedding a dedicated JSON Schema for payload defining a, b, version, and constraint, and explains the semantics of each mode. This fully addresses the 0% schema coverage.

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 'Compare semantic versions or test a version against a constraint,' which is a specific verb+resource statement that clearly distinguishes it from siblings like json tools or table converters. It also details two operational modes (compare vs. test constraint), leaving no ambiguity about what the tool does.

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 defines the two usage modes ('Either compare {a,b} or test {version,constraint}') and lists supported operators (>=, >, <=, <, =, ^, ~) and clause composition, giving clear context. However, it does not explicitly name alternatives or say when not to use this tool, so it falls just 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 excels: it discloses that first occurrence is kept, order is preserved, equality is JCS-canonical, and it reports what was removed and why. It also mentions determinism, guest rate limits, the option to use a member budget via api_key, and the Guild-signed provenance envelope—all beyond basic expectations.

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 moderately long but well-structured: a clear opening purpose, followed by behavior details, and then the required schema as a code block. Every prose sentence earns its place, and the embedded schema is necessary because it is not elsewhere in the input schema. It is slightly dense but appropriate for the tool's complexity.

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

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

The description covers operation, parameter constraints, output, operational context (rate limits, api_key), and provenance. The output schema is present in the description, so return values are clear. No major gaps are apparent, especially given the lack of annotations and the tool's 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 only specifies 'api_key' and an opaque 'payload' object with 0% coverage. The description compensates by embedding a full JSON Schema for 'payload', detailing required 'records' and optional 'keys' and 'case_insensitive'. It also explains that api_key is optional for guests but can be used for member budget, adding crucial 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 opens with a clear, specific verb+resource: 'Deduplicate JSON records exactly, optionally by key subset.' This distinguishes it from siblings like ag_json_canonicalize (which canonicalizes rather than removes duplicates) and ag_data_record_link (which links records).

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 context through the 'optionally by key subset' and 'case-insensitive' options, but it does not explicitly state when to use this tool vs alternatives or when not to use it. No comparison to sibling tools like ag_data_record_link is provided, so 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 of behavioral disclosure, and it does so thoroughly. It explains the algorithm (greedy best-first, normalized similarity ratio), the threshold mechanism, return values (matched pairs with scores, unmatched indices), determinism, fixture verification, guest rate limits, the optional api_key benefit, and the Guild-signed provenance envelope. This far exceeds basic transparency.

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 structured from summary to algorithm to usage to schema, with each sentence contributing unique information. It is compact given the tool's complexity, avoiding filler while including necessary details like rate limits and provenance. The embedded schema is redundant with nothing else in the description and is essential for correct 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 tool with nested payload schema and no annotations, the description covers all critical aspects: what it does, how it works algorithmically, parameter details via schema, output behavior, determinism, authentication (api_key), and rate limits. The output schema is provided separately, and the description mentions the provenance envelope, ensuring the agent has enough context to use 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 input schema only exposes api_key and a generic payload object, leaving the payload structure undefined. The description compensates by embedding the full JSON Schema for payload, specifying required fields, constraints (e.g., minItems, threshold range), and the meaning of threshold and key fields through prose like "caller-set threshold" and "chosen key fields." It also explains the api_key parameter's purpose. This fully makes up for the 0% schema_description_coverage.

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 and actionable statement: "Fuzzy-match records across two lists by a key field." This clearly identifies the verb (fuzzy-match), the resource (records), and the scope (two lists), distinguishing it from siblings like ag_data_dedupe which likely operates on a single list. The later phrase "Entity-resolution lite" further positions the tool's purpose.

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 "Entity-resolution lite: deterministic and auditable" and "free for guests," but it never explicitly states when to use this tool over alternatives or when not to use it. There is no mention of sibling tools like ag_data_dedupe for single-list deduplication, so the guidance is suggested rather than explicit.

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

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

With no annotations provided, the description fully discloses behavioral traits: deterministic, fixture-verified, free for guests but rate-limited, and returns a Guild-signed provenance envelope. It also specifies the required payload schema and that the same canonicalization is used for Agent Guild's own credentials, giving agents confidence in its 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?

The description is a bit long but well-organized: purpose first, then use cases, behavior, and schema. The embedded JSON schemas are necessary to clarify the expected input and output, and every sentence contributes value. 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?

The description is complete for this tool's complexity. It includes purpose, use cases, behavioral details, an explicit input schema, and an output schema, so agents know exactly what to expect. The presence of an output schema relieves the description from explaining return values, but it still does so succinctly.

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 description coverage is 0%, but the description compensates by explicitly defining the payload structure ('must match this JSON Schema') and explaining the api_key parameter ('pass your Guild api_key to use your member budget'). The description adds essential meaning beyond the input schema, though it could be slightly clearer about the api_key's optionality.

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 specific function: 'RFC 8785 (JCS) canonical form + sha256 of any JSON value.' This goes beyond a generic verb and distinguishes the tool from siblings like ag_json_validate or ag_json_diff by focusing on canonicalization and hashing for content addressing, dedupe, and signatures.

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 use cases are given: 'use for content-addressing deliverables, dedupe keys, and signature payloads.' It also notes the deterministic nature, which explains when this is preferred. While it doesn't explicitly mention alternatives or exclusions, the use-case context is clear enough for an agent to select this tool over 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 fully discloses behavior: deterministic, fixture-verified, capped at 500 changes, rate-limited for guests with optional api_key, and a Guild-signed provenance envelope. It also embeds the required payload schema and output schema. This far exceeds minimum disclosure and gives the agent confidence in side effects and limits.

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 purpose, then logically moves to use case, behavior, and schemas. Each sentence contributes critical information; the included JSON schemas replace verbose prose. It is well-structured and not bloated.

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

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

The tool is fully specified: input payload schema, output schema, change cap, determinism, provenance, and authentication context. The presence of the output schema means return values need no further explanation. For a complex diff tool, this is complete.

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

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

Despite 0% schema description coverage, the description compensates by providing the complete payload schema with required 'a' and 'b' fields. It also explains api_key usage in the rate-limit context. This gives agents full parameter meaning beyond names and 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?

The description opens with 'Structural diff of two JSON values with per-path changes,' using a specific verb and resource. It distinguishes itself from sibling JSON tools like validate, canonicalize, and path_extract by focusing on diffing. The later mention of 'added/removed/changed paths' reinforces the unique purpose.

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: 'Use to verify an agent's output changed only what it was asked to.' This gives clear context, though it does not name alternatives or provide exclusion criteria. The sibling tools are not referenced, missing the 'vs alternatives' element that would earn 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 provided, the description carries the full burden. It discloses 'never throws on a missing path', 'deterministic', 'fixture-verified', 'free for guests (rate-limited)', and 'returns a Guild-signed provenance envelope'. It also specifies the exact payload schema, covering input constraints. Missing details about error behavior on invalid payloads, but overall transparent.

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, followed by behavioral details and a mandatory JSON schema. Each section is purposeful; the embedded schema is essential despite making the description longer. Overall, it is well-structured and every sentence contributes value.

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 includes the exact payload schema, which is critical given the vague input schema. It also mentions the provenance envelope and references the output schema (already provided externally). All necessary information for correct invocation is present, making the tool fully usable without additional lookups.

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 only defines payload as an object with additionalProperties true, which is highly generic. The description fully compensates by providing a strict JSON Schema for payload, complete with required 'value' and 'paths' array, minItems/maxItems, and additionalProperties false. It also explains api_key as optional for using a member budget, adding meaning beyond the schema.

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

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

The description uses the specific verb 'Extract' and clearly identifies the resource as a 'JSON value' with path syntax like 'items[0].name'. It distinguishes this tool from siblings (ag_json_diff, ag_json_validate, etc.) by focusing on path-based extraction and mentioning 'never throws' and 'stricter than asking a model to read a field'.

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 compares to an alternative ('Cheaper and stricter than asking a model to read a field'), which gives clear usage context. It also mentions rate-limiting and api_key for member budget, providing practical guidance on resource usage. It does not explicitly contrast with sibling JSON tools, but the purpose is distinctive 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?

With no annotations, the description carries the full burden. It discloses determinism, fixture-verification, rate limits, api_key usage, and the exact repair steps. However, it claims 'Returns the result plus a Guild-signed provenance envelope,' yet the provided output schema (with additionalProperties: false) does not include such an envelope, creating a minor inconsistency.

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 relatively long but dense with useful information. It front-loads the main purpose and uses a clear flow: what it does, how to use, constraints, and return value. Including the full schemas adds length but is valuable; still, it could be tightened.

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 output schema is provided, the description still adds essential context: use case, repair behavior, rate limits, auth, and return contents. For a tool with moderate complexity, this is comprehensive and allows an agent to select and invoke it 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 0%, but the description compensates by embedding the exact JSON Schema for `payload` and explaining `api_key` ('pass your Guild api_key to use your member budget'). This fully clarifies both parameters beyond what the outer input schema offers.

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 repairs malformed JSON into parseable JSON, with a specific verb ('repair') and resource ('malformed JSON'), and distinguishes it from sibling tools like json_validate and json_canonicalize by mentioning specifics like stripping code fences and fixing Python/JS literals.

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 'Use when a model or upstream tool emitted JSON that json.parse rejects,' giving clear usage context. It does not name alternative tools or state when not to use it, so it falls short of the highest bar.

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. It discloses determinism, fixture-verification, guest rate-limiting, the option of using an api_key for higher limits, and the return of a Guild-signed provenance envelope. It also imposes a strict payload schema beyond the input schema, which is important behavioral context.

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 primary purpose. Each subsequent section adds necessary detail: output characteristics, pricing/auth, and precise payload/output schemas. It is long but efficient; the embedded schemas replace what would otherwise be lengthy prose. No wasted sentences.

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

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

The tool has a complex nested payload and an output schema. The description provides both schemas explicitly, explains the return value (result plus provenance envelope), and covers usage constraints (rate limits, api_key). It is complete enough for an agent to invoke the tool correctly without further context.

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 provides no descriptions for api_key or payload (0% coverage). The description compensates fully: it explains the api_key's role in using a member budget, and it explicitly provides a restrictive JSON Schema for payload (example array, min/max items, additionalProperties false) that goes far beyond the loose 'object' type in the schema.

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

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

The description opens with a clear, specific statement: 'Infer a JSON Schema from example instances.' It further details the exact behavior (draft-2020-12 schema, merging types, required keys, array item schemas), which distinguishes it from sibling tools like ag_json_validate or ag_json_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 use case is clearly implied: take example instances and produce a schema. It does not explicitly mention alternatives or when-not-to-use, but the description is unambiguous about its purpose. For a tool with many JSON siblings, explicit exclusions would be ideal, 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?

With no annotations, the description fully discloses behavior: deterministic, fixture-verified, rate-limited, returns a Guild-signed provenance envelope, and caps errors at 50. This goes well beyond the basic 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?

The description is moderately sized, front-loaded with a clear one-liner, and well-structured with paragraphs for usage, behavior, and schemas. The embedded JSON schemas add length but are informative.

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

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

The description covers purpose, usage, behavioral traits, parameter structure, and output contract within a single block. The inclusion of the payload sub-schema and output schema makes it fully self-contained for an agent.

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 provides no descriptions (0% coverage), but the description gives a full JSON Schema for `payload` and explains `api_key` as a way to use member budget. This compensates for the schema 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 opens with 'Validate a JSON instance against a JSON Schema (draft 2020-12)', a specific verb+resource statement. It further clarifies it validates any JSON value and returns structured errors, distinguishing it from sibling JSON tools like ag_json_diff or ag_json_repair.

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 states 'Use before passing data across an agent boundary', providing a clear use case. It also mentions free-for-guests and rate limits, though it doesn't explicitly contract with alternative validation 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?

No annotations are provided, so the description carries the full burden of transparency. It discloses key behavioral traits: determinism ('Deterministic, fixture-verified'), rate limiting ('free for guests...rate-limited'), the return of a 'Guild-signed provenance envelope', and a strict payload schema ('MUST match this JSON Schema'). This goes well beyond minimal 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?

The description is front-loaded with a concise summary, then adds necessary details about usage, behavior, and parameter constraints. It includes two schemas, which are justified but make the text longer than ideal. Every sentence contributes information, so it earns a high score, though it could be tightened slightly.

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 provides a complete picture for a tool with a complex payload: it defines the input parameters, the output schema, behavioral guarantees (deterministic, provenance), and usage context (alternative to model-based reading). Given the presence of an output schema, it need not describe return values further. It is self-contained and leaves no critical 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?

The input schema in the structured data is highly generic (payload object with additionalProperties: true, plus an api_key), offering zero description of parameters. The description fully compensates by embedding a detailed JSON Schema for the payload, specifying csv (string, maxLength 60000), delimiter (string, maxLength 1), and has_header (boolean), along with required fields. This gives the agent all necessary semantic information.

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

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

The description opens with a specific verb phrase 'Parse CSV/TSV text into JSON row objects', clearly stating the tool's function and resource. It distinguishes itself from sibling tools such as ag_table_json_to_csv, which performs the reverse operation, thereby making the purpose unambiguous.

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

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

The description explicitly positions the tool as a 'Deterministic alternative to model-based table reading', giving a clear context for when it should be used. It also mentions cost/rate limits (free for guests, pass api_key for member budget) which aids in usage decisions. However, it does not explicitly name or contrast with specific sibling tools, so it falls short of a full when-to-use/when-not-to-use guide.

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 fully discloses behavioral traits: it is deterministic, fixture-verified, free for guests but rate-limited, requires optional api_key for member budget, and returns a provenance envelope. It also details column order behavior, nested value encoding, and payload constraints. No contradictions with annotations exist.

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 well-structured and front-loaded with the core action, followed by key behaviors and then the JSON Schema. Each sentence adds value: column order, nested encoding, determinism, rate limits, and provenance. It is slightly long due to the inline schema, but that is justified for completeness.

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

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

The tool is moderately complex (nested objects, output schema, auth considerations), and the description covers everything: input requirements, output schema, return envelope, rate limits, and deterministic behavior. It also provides the exact JSON Schema for payload and output, leaving no ambiguity for the AI agent.

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 0% description coverage, but the description compensates by embedding a full JSON Schema for the payload, defining rows (array of objects, 1-5000) and columns (array of strings), and explaining the api_key purpose. This gives the agent complete parameter understanding beyond the bare schema.

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

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

The description clearly states a specific action ('Serialize an array of JSON objects to CSV') and a resource ('array of JSON objects'), with details distinguishing it from the reverse sibling ag_table_csv_to_json. It also explains the output format, making the tool's purpose unambiguous and unique among siblings.

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

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

The description provides clear context on when to use the tool (converting JSON objects to CSV, with stable column order and nested value JSON encoding). However, it does not explicitly mention when not to use it or point to alternatives, though the sibling ag_table_csv_to_json is an obvious reverse case. It also notes rate-limits and api_key usage, adding practical 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 burden and does so thoroughly. It discloses determinism, fixture verification, guest rate limits, the option to pass an api_key for a member budget, and the inclusion of a provenance envelope. These are concrete behavioral traits beyond what annotations could provide.

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

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

The description is front-loaded with purpose and usage, followed by concise behavioral notes and necessary schema details. Every sentence adds value; the embedded JSON Schema is justified because the tool's input schema is under-specified. No fluff or redundancy.

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

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

The tool has a rich description that covers what it does, when to use it, constraints (max input size, additionalProperties false), cost/auth behavior, and output format. Even with no annotations, an agent has enough context to invoke it correctly and 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 input schema only shows an opaque 'payload' object, but the description compensates by embedding the exact JSON Schema for payload, including the required 'markdown' property, its maxLength, and the constraint on additional properties. It also explains the optional api_key parameter in context of rate limits. This is far beyond the schema alone.

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 starts with a specific verb+resource: 'Extract structured tables from markdown text.' It further specifies the exact input format ('GitHub-style pipe tables') and the output ('columns + rows per table'), which distinguishes it from sibling table tools like ag_table_csv_to_json and ag_table_json_to_csv.

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 usage context: 'Use on model output or docs before downstream structured processing.' It does not explicitly name alternatives or exclusions, but for this niche markdown-extraction tool, the intended scenario 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?

With no annotations provided, the description carries the full burden. It discloses determinism ('Deterministic, fixture-verified'), per-item error handling ('one bad date never fails the batch'), rate limits and budget usage ('free for guests... pass your Guild api_key'), and the return of a signed provenance envelope. This is rich behavioral context beyond any structured annotation.

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

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

The description is longer due to embedded JSON schemas, but each section is purposeful. It is front-loaded with the primary purpose, followed by behavior, authentication, and schemas. The structure is logical and not bloated, though the inline schemas add necessary length.

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

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

Given the tool's complexity and the absence of annotations, the description is exceptionally complete. It covers input, output, error semantics, auth/budget, determinism, and provenance, while the output schema already documents the return shape. No critical context 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 actual input schema only defines `payload` as a generic object and `api_key` without detail. The description compensates by embedding the exact payload JSON Schema, specifying `dates` (array of strings, 1-500 items) and `dayfirst` (boolean), and explaining the role of `api_key`. This fully clarifies parameter semantics.

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

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

The description begins with a specific verb and resource: 'Normalize arbitrary date strings to ISO 8601.' It provides concrete examples of input formats and clearly distinguishes the tool from siblings like ag_text_regex_extract, which handles regex extraction rather than date normalization.

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

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

The description gives clear context on when to use the tool: when messy date strings need parsing. However, it does not explicitly mention alternatives, when not to use it, or exclusion criteria. Thus, the usage guidance is implied rather than explicit.

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

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

With no annotations, the description carries full burden and excels in transparency. It discloses safety guards (pattern length cap, nested-quantifier rejection, match-count cap), determinism, rate-limit information, and the Guild-signed provenance envelope, providing rich behavioral context.

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 a concise purpose statement, followed by essential safety and provenance details, then the payload and output schemas. Every sentence adds value with no fluff, and the structure is well-organized.

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

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

For a regex extraction tool with safety considerations, the description is highly complete. It covers input structure, output structure, safety constraints, determinism, rate limits, and provenance, leaving minimal ambiguity for the agent.

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 outer input schema simply has 'api_key' and 'payload' with no descriptions, but the description supplies the complete payload schema and explains key parameters like 'pattern' and 'text' indirectly. This greatly enhances the agent's ability to construct valid calls beyond the bare schema.

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

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

The description clearly identifies the tool as regex extraction over text, with a specific verb ('extract') and resource ('text'). It explicitly mentions returning matches with groups and offsets, distinguishing it from sibling tools like ag_json_path_extract.

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 clear context for when to use the tool: any time regex extraction on text is needed. It does not explicitly mention alternatives or when-not-to-use, and there are no exclusions stated, but the specific regex scope and safety guards imply appropriate use cases.

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. It discloses that the operation is free, grows a shared trust graph, requires authentication, defines the rating scale (0..1), and specifies the return shape ({id, verified}). Minor gaps remain, such as idempotency or reversibility, but overall it provides good behavioral context beyond the 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?

The description is concise and well-structured: a one-sentence purpose, a rating note, an auth instruction, a concrete example, and a return type. Every sentence adds value with no fluff, and the example effectively demonstrates parameter usage.

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

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

Given 5 parameters, 0% schema coverage, no annotations, and an output schema, the description covers most essentials: purpose, rating semantics, authentication, an example, and return shape. The only notable omission is task_id, and edge cases/error handling are not discussed, but the tool is simple enough that this is adequate.

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 clarify parameters. It explains issuer_api_key ('from guild_register'), rating (scale and example), and provides examples for subject_id and capability. However, task_id is completely omitted from the description, and the relationship between rating and 'vouch vs. warn' is only implicit. This partial coverage earns a middle score.

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's purpose: 'Vouch for (or warn about) work another agent did for you.' It uses a specific verb ('vouch'/'warn') and resource ('work', 'trust graph'), and the example call with parameters disambiguates it from sibling tools like guild_register or guild_prove.

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 clear context for when to use the tool—when you want to rate another agent's work—and includes a prerequisite ('Authenticate with YOUR api_key from guild_register'). However, it does not explicitly mention alternatives or when-not-to-use scenarios, though the sibling tool names imply related but distinct operations.

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 full burden. It discloses the payment model (paid trust read, same as GET /search), the x402 challenge for unpaid use, payment methods, and free soft-launch status. It also describes the return type and null possibility, though it omits error cases and the definition of 'safest'.

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 front-loaded with the core purpose. The payment note, example, and return format are each in distinct short paragraphs, with no redundant 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?

Covers purpose, usage, payment behavior, example, and return shape, which is solid for a selection tool with no output schema. However, it lacks documentation for 'min_trust' and does not clarify where valid capabilities originate (e.g., ag_capabilities), leaving minor completeness 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 coverage is 0%, so the description must explain all parameters. It only implicitly covers 'capability' via an example and 'api_key' in the payment context, leaving 'min_trust' completely unexplained. This is a significant gap for a required-parameter tool.

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 clear, specific purpose: find the single safest agent for a given capability, returning null if none qualify. This distinguishes it from sibling tools like guild_search by emphasizing 'best agent' selection. The example further clarifies the verb and resource.

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 tells the agent to 'Call this first, before hiring or delegating,' providing a clear primary use case. It does not explicitly mention alternatives or when not to use, but the contextual cue is strong enough for correct usage.

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 full behavioral burden. It discloses that this is a paid operation, explains the x402 payment challenge mechanism, how to retry with payment, the api_key sandbox behavior, and how to interpret estimate vs. confidence. This is rich, actionable behavioral context far beyond what structured fields would provide.

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

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

The description is long but front-loaded with the core purpose and structured into clear sections. Every sentence adds value, covering payment, example, return shape, and alternatives. However, it could be slightly tightened without losing key information, so it earns a 4 rather than 5.

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 explains the return fields in detail, covers the payment flow and edge cases (unpaid call, retry, api_key), and provides usage context with a concrete example. Despite the output schema existing, this description is self-sufficient and complete for a complex 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. It explains the primary parameter 'capability' through the example 'fact-check' and the overall purpose. It also clarifies 'api_key' as a funded key for SANDBOX credits. This fully bridges the schema 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 opens with 'START HERE' and clearly states the tool's function: 'vet a `capability` before you delegate.' It specifies the primary output (best-evidenced agent, evidence verdict, shortlist, PROOF) and distinguishes itself from siblings by recommending guild_search / guild_risk_score for finer control. This fully satisfies the verb+resource+differentiation standard.

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 positions this as the starting point ('START HERE') and provides an example call. It also tells users when to use alternatives: 'Use guild_search / guild_risk_score for finer control.' This explicit when-to-use and when-not-to-use guidance exceeds the minimum.

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 full burden and excels: it discloses that the payload is never sent (only SHA-256), requires a valid agent-guild/caller-proof/v1, and explicitly lists attestation boundaries (integrity, sender auth, issue time—not payload truth, recipient acceptance, or settlement). This is rich behavioral 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?

Every sentence earns its place. The description is front-loaded with 'PAID' and purpose, followed by concise behavioral rules, limits, kinds, and an alternative. 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?

The description covers the core context: purpose, payment, security model, attestation limits, and alternative tool. An output schema exists, so return values don't need explanation. However, parameter semantics are incomplete, and prerequisites for obtaining/using the caller-proof are not detailed, leaving some gaps for a paid tool with this 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?

Schema description coverage is 0%, so the description must compensate. It clarifies payload_sha256 (hash of payload), recipient, and kind (via listed kinds), but leaves many parameters unexplained: nonce, value, reply_to, resource, ttl_seconds, message_context, constraints_sha256, payload_media_type, and api_key. With 12 parameters, this is insufficient for correct invocation.

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 'Seal one exact machine message or economic intent,' providing a specific verb and resource. It clearly differentiates from sibling tools by explicitly directing users to guild_envelope_verify for free checks.

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 tool is 'PAID' and gives an explicit alternative: 'Use guild_envelope_verify for free checks.' Also provides usage context by listing allowed kinds and explaining the requirement for a caller-proof, giving clear when-to-use guidance.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It excellently explains the semantic limits: 'A valid result means exact integrity, Guild provenance and authenticated sender at issuance — not that the committed message is true or that its recipient accepted it.' It also states the free/no-trust nature, giving a clear behavioral profile beyond the 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?

The description is three concise sentences, front-loaded with 'FREE,' and every sentence adds substantive meaning. No filler or repetition; it efficiently conveys purpose, prerequisites, and limitations.

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 thoroughly covers the verification semantics and limitations, but it fails to describe the envelope parameter entirely. Given the parameter is a complex nested object, this is a clear gap. The output schema exists, so return value documentation is not required, but input construction guidance is missing. Overall, it's minimally adequate but incomplete for reliable 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 schema has one parameter ('envelope') as an object with additionalProperties true, but the description provides zero detail about its structure or usage. Schema description coverage is 0%, and the description does not compensate. The agent can verify the tool but has no guidance on how to construct or understand the envelope parameter, making this a major 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 states the tool's function: 'Verify a Guild-issued machine envelope and its expiry.' It uses a specific verb ('verify') and a distinct resource ('Guild-issued machine envelope'), which differentiates it from sibling tools like guild_verify or guild_prove_verify by focusing on the 'machine envelope' concept.

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 strong usage context: it's free, requires no key/payment/network trust, and explicitly defines what a valid result does and does not mean. This effectively tells the agent when to use this tool (when free, trustless verification is needed) and when not to (when verifying message truth or recipient acceptance). However, it does not explicitly name alternative tools for comparison, so it falls just 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 provided, the description carries the full burden of behavioral disclosure. It explains the escrow mechanism: funds are locked, worker is paid on release, a small Guild fee is deducted, and the returned object includes the worker's risk score. It also mentions authentication via api_key. This is good transparency for a financial tool, though it doesn't cover failure modes or rate limits.

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 concise, well-structured, and front-loaded. It explains the purpose in the first sentence, clarifies the workflow in the middle, and ends with a practical example. Every sentence adds value, and the example reinforces the parameter usage 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?

An output schema exists, so return values need not be detailed. The description covers the essential context: purpose, workflow, fee, risk score, and follow-up action. It might benefit from mentioning edge cases (e.g., non-release or insufficient funds), but for a well-annotated tool with a clear workflow, it is largely complete.

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

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

Schema coverage is 0%, so the description must compensate. It does so for key parameters: 'amount' is described as credits with a dollar conversion ('1000 credits = $1.00'), and the example clearly maps all four parameters to meaningful values (issuer_api_key, worker_id, amount, capability). It could define 'capability' more precisely, but the example offers a plausible usage (e.g., 'summarize').

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's function: 'Commission work from another agent by funding an escrow.' It specifies the verb (fund/open), the resource (escrow), and the overall purpose (safe value exchange). It also distinguishes itself from the sibling tool guild_escrow_release by explicitly mentioning 'call guild_escrow_release once you accept the delivered work.'

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 clear context on when to use the tool ('This is how agents safely exchange value for work without trusting each other') and a concrete example with parameters. It even references the next step (guild_escrow_release), but does not explicitly state when not to use it or mention alternative tools. Therefore it falls short of a 5, but is still strong.

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 burden of behavioral disclosure. It explicitly states the financial split (amount−fee to worker, fee to Guild), the reputation impact, and the authentication requirement (payer's api_key). It also mentions the return type (settlement detail). This is thorough and leaves no major behavioral trait undisclosed.

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

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

Two concise sentences plus a compact example. Every sentence adds meaningful information: what happens, who authenticates, what is returned, and how to call it. No filler or redundancy; the structure is front-loaded and easy to parse.

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 generally thorough, covering the settlement flow, authentication, and return. However, the rating parameter's role, range, or effect on settlement is not explicitly defined; only an example value is given. This minor gap prevents a perfect completeness score but does not materially impair an agent's ability to use the tool.

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

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

Schema description coverage is 0%, so the description must compensate. It successfully explains issuer_api_key (payer's key), escrow_id (the escrow identifier), and deliverable (the work product) via the example. Rating is only shown in the example without explicit meaning, but the example provides a concrete value and context implies it's a quality rating. This adds significant value beyond the bare schema.

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

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

The description opens with 'Accept delivered work and settle the escrow' – a specific verb+resource that clearly identifies the tool's function. It distinguishes itself from siblings like guild_escrow_open by detailing the settlement outcome (worker paid, Guild fee, transaction recorded), leaving no 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?

The description establishes clear usage context: it is for settling escrow after work has been delivered, and it explicitly states that the caller must authenticate with the payer's api_key. It does not name alternatives or exclusions, but the context is sufficient for an agent to infer when to use this tool versus others.

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 fully carries behavioral disclosure. It explicitly reveals that results separate registry claims from observed outcomes, never merges them, and includes a concrete metric (92.9% healthy, 33.9% complete task). This is rich, non-obvious behavioral context beyond basic search functionality.

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 tightly written: an opening phrase, a clear explanation of the core claim/observed distinction, a supporting stat, and an example. Every sentence adds value, and it's front-loaded with the main purpose. No fluff.

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

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

Given the presence of an output schema, return value details need not be in the description. The description covers purpose, key behavioral nuance, cost/auth (free, no key), and usage example. For a search tool with two optional parameters, this is comprehensive.

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 description must compensate. It provides an example using 'query' but does not explain 'limit' beyond what the schema shows (int, default 20). The example clarifies query usage, but limit semantics are left implicit. Adequate but not fully compensating for zero descriptions in schema.

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

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

The description clearly states the tool 'Search the public trust index of agent endpoints' with specific verb 'Search' and resource 'public trust index'. It differentiates from sibling guild tools by its unique focus on comparing registry claims vs observed behavior, which is a distinctive capability.

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 context by highlighting 'FREE, no key' and gives an example invocation. However, it does not explicitly contrast with sibling tools like guild_search or guild_check, so while context is clear, alternatives are not directly excluded or compared.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: it is free, requires no account/key, prices are dynamic, and it details the nature of each paid operation (e.g., evidence_bundle is a signed, portable, offline-verifiable snapshot). 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 well-structured with a clear front-loaded headline ('FREE. Returns every paid operation...') and organized sections for each operation. It is somewhat lengthy, but every detail contributes to understanding the tool's value. Minor redundancy ('No account' appears twice) prevents a perfect score.

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 an output schema exists (not shown but indicated), the description need not detail return format. It explains pricing dynamics, x402 settlement, the free nature, and the purpose of each paid operation. No significant gaps remain; the example usage also aids completeness.

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 0 parameters, so the baseline is 4. The schema coverage is 100% (empty schema), and the description reinforces that no parameters are needed ('guild_paid_operations()'). There is no additional parameter semantics required.

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 explicitly states 'Returns every paid operation with its CURRENT price, exact callable entrypoint, x402 settlement resource, and the free alternative to each.' This is a specific verb+resource with clear scope, and it differentiates from siblings like guild_attest or guild_watch by focusing on the catalog of paid operations.

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

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

Provides clear context: 'Call this tool (free) for the live figure, the exact route, and the free alternative to each paid operation.' It also explains why not to rely on hardcoded prices ('Prices are deliberately NOT written into this description'). However, it does not explicitly name alternatives or state when-not-to-use, so it falls slightly 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 full burden and does so well. It discloses that the tool returns a W3C Verifiable Credential or an error, explains offline verification against the Guild's did:key, and describes the portable nature. This is transparent about output and purpose, with no hidden side effects implied.

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 plus an example: concise, front-loaded, and every sentence earns its place. No filler or redundant 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 one-parameter tool with an output schema present, the description covers purpose, usage, return type, error case, and an example. It is fully complete for the tool's complexity and clearly guides 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 0%, so the description must compensate. It explains the parameter through context ('for agent_id') and a concrete example ('agent_id="agt_9x"'). It does not explicitly state the format constraints, but for a single self-explanatory parameter the example is sufficient.

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 'Get a portable, Guild-signed Agent Passport for agent_id' using a specific verb (Get) and resource (Agent Passport). It explains what the passport is (a Verifiable Credential of reputation) and distinguishes it from the sibling tool guild_verify by explicitly contrasting showing yours vs verifying theirs.

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 guidance is provided: 'Show YOUR passport to agents you want to work with; verify THEIRS with guild_verify.' This tells the agent when to use this tool and when to use the alternative, making the intended use case unmistakable.

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 full burden and delivers: discloses that it performs live checks, is not cached, returns 'unknowns' for unperformable checks, and excludes unknowns from the verdict. Provides statistical context and rationale, giving a clear behavioral profile without contradiction.

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

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

Every sentence serves a purpose: timing, cost, claim vs. proof, statistical justification, irreversibility rationale, distinction from cached badges, unknown-handling policy, and an example. The structure is logical and front-loaded with the most critical usage guidance.

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

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

The description is complete for a tool with an output schema: it covers why, when, and how to use it, explains the unknown handling, and provides an example. The output schema presumably details return values, so no need to duplicate that. Complexity is high, but the description addresses all necessary context.

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%, but the description adds meaningful context for the single 'url' parameter by identifying it as an agent endpoint and providing an example (guild_preflight(url="https://some-agent.example/a2a")). This compensates for the bare schema, though more explicit format constraints would push it to 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 description clearly states the tool is a preflight check run before delegating to or paying an agent endpoint, separating claims from proven behavior. It distinguishes itself from directory badges by being live and uncached, and the example invocation clarifies usage.

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 specifies when to use: 'in the moment BEFORE you delegate to, or pay, an agent endpoint you did not write.' Contrasts with cached directory badge tools, indicating when this live check is preferred over alternatives. Also notes the irreversibility of x402 transfers to emphasize timing.

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 payment requirement, output includes drift history/corroboration/policy verdict, and notes it is a paid read through the same gateway. It lacks details on api_key usage and failure behavior, but is substantially transparent.

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

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

Four focused sentences with a clear structure: value statement, differentiation, pricing, and a usage example. 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?

The tool has an output schema and simple params; the description covers purpose, pricing, and example, but omits explicit authentication/detailed output explanation. Still largely complete for a check 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%, and the description only provides an example using 'url'; the 'api_key' parameter is not described, so the burden is not fully carried.

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

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

Clearly states a deep pre-flight check that adds live checks, drift history, cross-source corroboration, and a policy verdict, and explicitly contrasts with the free guild_preflight.

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 frames when to use ('before you delegate or pay') and differentiates from the free guild_preflight, noting what the deep version uniquely provides and that the free version remains intact.

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 discloses key behaviors: returns a challenge, supports two verification modes (ed25519 vs api_key), is repeatable, and has no side effects. However, the phrase 'Completing it records a REAL guild-observed task' could be misread as a side effect of this tool, though the earlier disclaimer clarifies only guild_prove_verify has effects.

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 moderately detailed but well-structured, with a clear lead sentence, example, and return fields. Some extra prose on provenance and journey stages could be trimmed, but it remains focused and informative.

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 output schema and sibling context, the description provides a comprehensive picture: purpose, usage, effects, example, and return shape. It explains the tool's role in the journey and its relationship to guild_prove_verify, making it complete enough for an agent to select and invoke correctly.

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

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

The description adds meaning to the parameters: api_key is explained as the custodial confirmation method, and the example demonstrates usage with both agent_id and api_key. While it doesn't systematically document each param, it compensates for the 0% schema coverage by contextualizing their roles.

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 action ('Start the proving rung') and clearly identifies the tool's purpose: to return a challenge for a newcomer to prove identity. It explicitly distinguishes from sibling guild_prove_verify by noting 'only guild_prove_verify has effects,' making the tool's role unambiguous.

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

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

Provides explicit usage context: this is the one journey step a newcomer can complete alone with no counterparty, it is free and repeatable, and it has no effects (unlike guild_prove_verify). This tells the agent exactly when to invoke this tool versus its sibling.

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

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

With no annotations provided, the description fully carries the transparency burden. It discloses the write behavior (records a real task + receipt), the provenance label, the refresh-only behavior after 14 days, and explicitly states 'proving cannot be farmed.' It also details the two auth mechanisms and their effects, providing rich behavioral context beyond any structured annotation.

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

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

The description is dense but every sentence earns its place: it front-loads the core action and outcome, then covers re-proving behavior, auth methods, and return values. No fluff or repetition; the structure flows from purpose to usage to details.

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

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

Given the tool's complexity, the description covers the workflow (proving rung, liveness window), auth paths, return object, and even the 'cannot be farmed' constraint. It lacks explicit mention of the required agent_id and does not state 'you must call guild_prove first', though it implies it via the challenge reference. Overall, it is quite complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains api_key ('presenting your api_key IS the proof') and signature (hex ed25519 over the JCS-canonicalized challenge), adding meaning beyond the schema. However, the required agent_id parameter is never mentioned, leaving a gap in semantic coverage.

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's purpose: 'Complete the proving rung' and details the outcome (records a real task + receipt, advances to journey stage 2). It distinguishes itself from sibling tools by referencing the 'challenge' from guild_prove and describing re-proving behavior, making its unique role evident.

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 clear context on when to use the tool: first success versus re-proving after the 14-day liveness window. It also gives agent-specific guidance (custodial vs self-sovereign) and implies a prerequisite by referencing the challenge object from guild_prove. However, it does not explicitly name alternatives or when not to use, stopping short of full exclusion 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 full burden. It discloses authentication requirements (api_key from guild_register), automatic hashing of deliverable, storage of a graded receipt, and the condition for highest class ('guild_mediated') requiring proof. It does not mention idempotency or error behavior, but the provided details are substantial and go beyond mere operation naming.

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 dense paragraph but every sentence adds value: purpose, proof requirements, parameter semantics, and an example. It is front-loaded with the primary action and avoids filler. The length is appropriate given the tool's complexity (7 params, no annotations).

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

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

Given the tool's complexity and lack of annotations, the description covers authentication, proof conditions, parameter formats, and a usage example. The return value is likely documented by the output schema, so not explaining it here is acceptable. It does not discuss edge cases or failure modes, but overall it provides enough context 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 coverage is 0%, so the description must compensate. It explicitly explains `deliverable` (hashed for you), `deliverable_hash` (precomputed alternative), `outcome` and `rating` value ranges, and `issuer_api_key` (authentication). It also gives a full example covering all params. However, `worker_id` and `capability` are only implied, not explicitly defined.

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 'Record a collaboration in one call after another agent did work for you' and then enumerates the exact actions (creates task, content-addresses deliverable, stores receipt, writes attestation). This clearly distinguishes it from sibling tools by specifying the resource (collaboration ledger) and the specific high-level operation.

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 for when to use: 'after another agent did work for you' and 'This is how the shared record of who-did-good-work-for-whom gets built.' It mentions alternative proof pathways (escrow settlement, countersigned receipt, Guild-observed invocation) but does not explicitly name alternative tools to use instead, so it lacks explicit exclusion 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?

No annotations are provided, so the description carries the full burden. It discloses the secret api_key, its role in signing attestations, the one-time nature, and the return fields. This is exemplary transparency for a registration 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?

The description is front-loaded with the core purpose, followed by essential caveats, an example, and next steps. Every sentence earns its place and the structure is well-organized despite being multi-paragraph.

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 return fields, the secret key warning, attribution via src, and next steps. With an output schema present, the description adds necessary behavioral and usage context, making it complete for an agent registration 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 0%, but the description compensates with an example call (name and capabilities) and a detailed explanation of src. It doesn't fully define name/capabilities semantics, but the example implies their meaning, making it adequate for a 3-param tool.

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 'Register this agent on Agent Guild so others can find and vouch for you' with a specific verb and resource. It distinguishes itself from sibling tools like guild_attest and guild_prove by focusing on registration.

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 explicit context: 'Free, and you only need to do it once' and mentions the follow-up proving rung ('guild_prove → guild_prove_verify'). It also explains the src parameter usage with an example, giving clear when-to-use guidance and next steps.

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. It transparently discloses payment requirements ('PAID trust read', 'x402 challenge', 'pay via _meta["x402/payment"] or a funded api_key'), the free soft-launch status, and the inclusion of deprecated fields. This goes beyond basic parameter info and gives the agent a clear picture of side effects and prerequisites.

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 well-structured with a core purpose statement, a payment section, an example, and a deprecation note. It is slightly dense in the payment section, but every sentence provides actionable information, and the example makes the invocation pattern concrete.

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 lack of an output schema, the description does a good job explaining return values (estimate, confidence, explanation, collusion suspicion) and the trust-decision context. It also covers payment behavior, which is critical for invocation. Minor gaps exist around exact output structure and edge cases, but the description is sufficiently complete for a simple 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 0%, so the description must compensate. It provides an example using 'agent_id="agt_1a2b3c"' and mentions 'api_key' as a payment credential, but it does not formally describe each parameter's type, requirements, or default behavior. This partial compensation is useful but not complete, so a middle score is appropriate.

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

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

The description clearly states the tool's function: "The evidence view for one agent before trusting it with a task or payment." It names the key output fields (estimate, confidence, explanation, collusion suspicion) and distinguishes it from siblings by emphasizing the 'evidence view' and the asker's own decision threshold.

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 indicates when to use this tool: "before trusting it with a task or payment". It also conveys the decision framework ('Apply YOUR OWN threshold') but does not mention alternative tools or when not to use it, so it lacks explicit exclusions.

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

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

With no annotations provided, the description carries the transparency burden. It discloses the paid/cost nature ('PAID trust read'), the x402 challenge and payment mechanisms, the free-in-soft-launch state, and the exact return format. It doesn't explicitly state 'read-only' but implicitly conveys it via 'build a shortlist' and the trust read phrasing.

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

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

Every sentence earns its place: purpose, usage context, parameter clarification, cost/payment disclosure, example, and return format. It is compact yet information-dense, front-loaded with the core function, and avoids 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 no output schema, the description explicitly lists the return fields (`{id, name, trust, confidence, price_per_call, rank}`). It covers cost, payment, filtering, and usage. The example ties everything together. This is fully sufficient for an agent to select and 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?

Schema coverage is 0%, so the description compensates by explaining `min_trust` (0-100 filter), `limit` (caps list), and providing an example with `capability`. `api_key` is only indirectly referenced in the payment sentence, but the schema at least shows it as a string with default. The description adds meaningful semantics for three of four parameters.

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

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

The description opens with a specific verb and resource: 'Find agents that have a capability, ranked by attack-resistant trust.' This clearly states the tool's function and distinguishes it from siblings like guild_best_agent (selecting best) or guild_check (verifying). The scope (search by capability) is explicit.

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 clear context for when to use this tool: 'Use this to build a shortlist before delegating work.' It also notes the paid trust read behavior and mentions filtering parameters. However, it does not explicitly name alternative tools to avoid, so it stops short of a full when-not-to-use list.

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 full burden. It discloses that it returns both validity and live reputation (a helpful behavioral detail) and that it also serves as a discovery mechanism for Guild tools. It does not discuss error handling or side effects, but for a simple verification tool this is sufficient.

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

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

Two tight sentences plus a code example. Every clause adds value: purpose, output, live reputation, discovery, and usage syntax. 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?

Given low complexity (one param) and the presence of an output schema, the description covers the essential context. It explains what to pass, what comes back, and an unexpected side effect. It could nod to related tools, but the tool is simple and the description is adequate.

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 only names 'credential' as an open object. The description adds meaning via the example 'credential={...the VC they sent...}', clarifying it is the verifiable credential from the other agent. However, it does not describe the expected structure or required fields, so the compensation is partial.

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

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

The description opens with a specific verb and resource: 'Verify an Agent Passport another agent showed you.' It clearly states the return value (validity + LIVE reputation) and adds a unique secondary purpose (discovering the Guild's tools). This distinguishes it from sibling tools like guild_check or guild_prove_verify.

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

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

Provides clear context for when to use: after receiving a passport from another agent ('another agent showed you') and emphasizes live reputation to avoid stale snapshots. It does not explicitly name alternatives, but the use case is well-defined and implies this is the go-to verification tool.

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 must disclose behavioral traits itself. It does so effectively by explaining idempotency ('calling twice returns the same watch rather than billing twice'), pricing model ('charged only when it actually runs'), and the free provisioning aspect. It does not cover cancellation or error handling, but the key user-facing behaviors are transparent.

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 well-structured: the first sentence states the core purpose, the second adds key behavioral details, and the example provides concrete usage. Every sentence contributes value without redundancy, making it appropriately sized and 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?

Given that an output schema exists, return-value details are not needed. The description covers the essential provisioning behavior, pricing, and idempotency, and it mentions the related feed tool. However, it does not explain how to stop monitoring, whether interval_seconds is in seconds, or any rate limits, which would improve completeness for a tool in a large sibling set.

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. The example clarifies that 'url' is the endpoint to monitor and 'api_key' is likely an authentication credential, but 'interval_seconds' is never explained beyond the vague reference to 'recheck cycle.' This leaves the default unit and range unclear, which is a notable gap for a required-schema field.

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's function with a specific verb+resource: 'Self-provision CONTINUOUS monitoring of an endpoint.' It also differentiates from siblings by explicitly mentioning 'guild_watch_feed' for reading change feeds, implying this tool is for setting up the watch itself, not consuming its output.

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

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

The description provides context on when to use this tool ('No onboarding, no human, no sales call') and hints at alternatives by directing to 'guild_watch_feed' for reading the change feed. However, it does not explicitly contrast with other sibling tools like guild_check or guild_preflight, leaving some ambiguity about when continuous monitoring is preferred over one-off checks.

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. It discloses that the operation is free ('Free — you already paid for the cycles that produced it') and that the output is machine-readable, which adds useful context. However, it does not mention potential errors, pagination, or any side effects beyond the implied read-only nature.

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 exceptionally concise, with two sentences. The first sentence front-loads the core purpose, and the second adds a cost-related behavioral note. There is no wasted wording, and every sentence contributes meaningful 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?

The tool is simple with only two parameters and an output schema, so the description does not need to explain return values. However, it lacks details about the change feed's behavior (e.g., whether it is incremental, ordered, or time-limited). Given the existence of an output schema, the description is minimally adequate but leaves several behavioral aspects 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?

The schema has 0% description coverage, and the description provides only a vague implication that watch_id refers to a provisioned watch. The api_key parameter is not addressed, and there is no guidance on formats or where to find watch_id. The description does not compensate for the lack of schema descriptions.

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

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

The description clearly states 'Read the machine-readable change feed for a watch you provisioned.' This specifies the verb (read), the resource (change feed for a watch), and the scope (a watch you provisioned), distinguishing it from sibling tools like guild_watch which likely provisions the watch.

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 implicitly indicates this tool is used after provisioning a watch ('for a watch you provisioned'), providing clear context. It does not explicitly mention alternatives or exclusions, but the sibling list makes it apparent that guild_watch is the provisioning counterpart.

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