Peer Lookup Tools

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 discloses a size limit (4096 bytes) and specifies that decode returns UTF-8 text only, which is useful. However, it does not describe error behavior or what encode returns, but the given details exceed typical descriptions.

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, highly concise, and front-loaded with the primary purpose. It includes only essential information with 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?

The tool has three required parameters, no output schema, and no annotations. The description omits the output format for encode, how 'data' should be interpreted (text vs. bytes), and any error cases. While the reference to the API endpoint provides a hint, it is insufficient for a fully informed 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?

Schema coverage is 0% and the description does not explicitly explain the parameters. It mentions operations and encodings that map to the enum fields, but does not clarify the 'data' parameter or the relationship between input and output. The description fails to compensate for the lack of parameter documentation.

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 'Encode/decode' and the resource 'base64, base64url, or hex'. It also adds constraints (max 4096 bytes) and output behavior for decode, which distinguishes it from sibling utility tools like lab_hash or lab_json.

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 for encoding/decoding tasks but does not explicitly state when to prefer this tool over alternatives. It references an API endpoint ('Same as POST /api/v1/codec') but does not compare to sibling tools. No exclusions or conditions are given.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It does state 'static curated' and 'Same data as GET', which imply a read-only, non-mutating operation. However, it does not mention potential side effects (none expected), authentication requirements, rate limits, or what happens on error or with invalid input. The description is too sparse to fully inform the agent 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 a single, compact sentence broken into three clauses: purpose, equivalence to an API, and filter note. It is front-loaded with the core function, and every word earns its place. No fluff or unnecessary elaboration.

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

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

For a simple lookup tool with one optional parameter and no output schema, the description provides enough context: it identifies the resource (agent doors), hints at the content (Peer Lookup, boards/catalogs), and mentions the optional filter. It does not describe the return format, but the term 'directory' implies a list, and the absence of an output schema lowers the requirement. Minor omissions like error behavior are not critical for 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?

Schema coverage is 100% and the parameter 'kind' has a description ('Optional filter by entry kind') and an enum. The tool description redundantly mentions 'Optional kind filter' without adding new details such as default behavior or the effect of omitting the filter. Since the schema already documents the parameter, the description adds no meaningful semantic value beyond what is structured.

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: it is a static curated directory of agent doors, including Peer Lookup and boards/catalogs. The verb 'lookup' is implicit but the resource is explicit, and it is obviously distinct from sibling tools like lab_hash or lab_time.

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: an agent would use this when it needs to list or look up agent doors. It also mentions 'Same data as GET /api/v1/directory', hinting at an alternative REST API, but does not explicitly state when to prefer this tool over that or over any other alternative. No exclusions or conditional guidance are provided.

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 behavioral disclosure burden. It adds meaningful non-obvious details: the 4096-byte limit after UTF-8 encoding and the fact that the body is not stored, which is relevant for agents concerned with data persistence. It does not describe the return format, but the purpose implies a hash value.

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 short sentences deliver the purpose, a hard constraint, and a behavioral note. Every sentence earns its place, and the key operation is front-loaded. No redundant filler.

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

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

For a single-parameter, low-complexity tool, the description covers purpose, input constraints, and a privacy-relevant behavior. It does not explicitly state the output format, but 'SHA-256 of a UTF-8 string' sufficiently implies a hash string. The reference to the equivalent POST endpoint adds useful integration 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 description coverage is 100%: the 'data' parameter already documents that it is UTF-8 text and mentions the 4096 encoded-byte limit. The description adds little beyond restating this constraint, so it does not significantly enrich parameter understanding 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 states a specific operation: compute the SHA-256 hash of a UTF-8 string, with a byte limit. This clearly distinguishes it from sibling tools like lab_uuid or lab_time, though it does not explicitly name any alternative or contrast with lab_codec.

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: it is for hashing UTF-8 text, with a maximum input size and a privacy note that the body is not stored. It does not explicitly say when to prefer this over sibling tools, but for a simple utility this is sufficient contextual 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 available, the description carries the disclosure burden and does add useful behavior: the 8192-byte size cap and the string-type requirement. However, it does not disclose what happens on invalid JSON, whether operations fail or degrade gracefully, or what the return shape is — gaps an agent would want filled for a validation tool.

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

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

Two sentences with no wasted words. The core operations are front-loaded, followed by the two most decision-relevant constraints (string input, size limit) and the API equivalence. Everything present earns its place.

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

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

For a low-complexity tool (2 params, one enum), the description covers the input contract but is silent on output/return semantics and error behavior, and there is no output schema to compensate. An agent cannot know what 'validate' returns on success versus failure without probing 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 50% (data is described, op is not). The description names the three op values, which partially compensates for the undocumented op parameter, and adds the byte-size constraint on data. This is baseline-adequate given the enum already enumerates the valid choices.

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

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

The description states a specific action set — validate, pretty-print, or canonicalize — applied to a clear resource (JSON text). This distinguishes it from siblings like lab_hash and lab_codec, and the parenthetical 'data must be a string' further disambiguates the input contract.

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?

No guidance is given about when to choose this tool over alternatives, nor which op to use in which situation. 'Same as POST /api/v1/json' is an API equivalence note, not usage guidance. The only constraint mentioned is the 8192-byte limit, which is a boundary condition rather than a when-to-use signal.

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 are absent, so description carries full burden. The description is minimal but accurately describes a GET liveness endpoint, implying no side effects. It doesn't disclose response format or error behavior, which is a minor gap for such a simple 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 extremely concise with no unnecessary words, and it is a single clear sentence. It's perfectly sized for a zero-parameter tool.

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

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

Given the tool's simplicity, the description is complete enough. It lacks details on return values, but no output schema exists, and the description could benefit from a note on what a successful ping returns, but this is minor for a liveness check.

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 empty, so the description doesn't need to explain parameters. The baseline for 0 params is 4, and the description adds the semantic of being a liveness check, which 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 explicitly states the tool performs a liveness check and maps it to a known HTTP endpoint, which is clear. However, it does not distinguish it from sibling tools, though none seem to be liveness-related, so context provides some separation.

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

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

The description implies the tool is for checking if the service is alive, but doesn't provide explicit guidance on when to use it vs alternatives. It is implied that it's a health check, but no exclusions are stated.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states the time source is the Worker clock and explicitly rules out external time APIs, preventing a common misconception. It does not describe the response format, but for a simple no-parameter time getter, the behavior is transparent enough.

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 one tight sentence with no filler. It front-loads the core purpose, then adds a useful reference to the equivalent API endpoint and a clarifying exclusion. Every word earns its place.

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

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

Given the tool's trivial complexity, zero parameters, and simple purpose, the description is largely complete. It names the time source, timezone, and an equivalent endpoint. It does not specify the exact return format, but since there is no output schema and the output is essentially 'current UTC time', this is a minor gap.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter meaning, and it adds no unnecessary param-related detail. This is appropriately handled.

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 the tool returns the current UTC time from the Worker clock, matching the endpoint GET /api/v1/time. This distinguishes it from the sibling tools, none of which are time-related. The noun phrase 'Current UTC time' is specific enough for an agent to understand the tool's exact function.

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: use this tool when you need the current UTC time from the Worker clock. The explicit statement 'No external time API' acts as an exclusion, telling the agent this tool does not rely on external services. It does not name alternative tools, but no sibling is a time tool, so this is sufficient.

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 burden. It discloses the default version and the batch limit, and 'Same as GET' hints at a read-only style operation. However, it doesn't describe validation return behavior, how invalid UUIDs are reported, or what happens when both id and count/action are provided.

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 short sentences, front-loaded with the core purpose, followed by the key batch constraint and an API reference. Every word earns its place with no filler 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 is simple and the description covers the main purpose, default version, and batch cap. However, with no annotations and no output schema, the absence of validation result semantics and parameter-interaction guidance leaves a noticeable gap, even for a lightweight utility.

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

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

Schema coverage is only 25%, but the description compensates by explaining the action enum (generate/validate), the default version (7), and the batch count semantics. This adds meaning beyond the raw enums and integer limits, though it doesn't explicitly state which parameters apply to which action.

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

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

The description names the exact operation ('Generate or validate UUIDs'), specifies the default version (v7), and adds a concrete constraint ('Batch generate up to 20'). This clearly differentiates lab_uuid from the sibling tools like lab_codec or lab_hash without needing to inspect schemas.

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

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

The description clearly states the intended use: generate or validate UUIDs, with a batch option and a default version. It doesn't explicitly list exclusions or alternatives, but no sibling tool competes for this job, and 'Same as GET /api/v1/uuid' provides a recognizable API context.

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 behavioral disclosure burden. It states exactly what is returned and adds a strong privacy guarantee ('Never returns IP'). The reference to GET implies a read-only operation, but it does not mention authentication, rate limits, or error 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 three short, direct clauses with no filler. The core return contract comes first, followed by the privacy guarantee and endpoint mapping, which is ideal for quick agent parsing.

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, no-output-schema tool, the description fully explains what the agent will receive and adds the important 'Never returns IP' constraint. The endpoint reference provides additional authoritative context, making this complete enough for correct invocation.

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

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

The tool has zero parameters, so there are no parameter semantics to document. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on return value semantics instead.

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 that the tool returns a request_id and day-scoped actor_pseudonym for log correlation, and explicitly denies returning IP addresses. It also maps to a specific endpoint (GET /api/v1/whoami), making its purpose distinct from the sibling utility tools.

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

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

The phrase 'for log correlation' gives a clear intended use case, and 'Never returns IP' sets an expectation about data sensitivity. However, it does not explicitly say when not to use it or compare it with alternatives, though none of the siblings are obvious alternatives.

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