AI Agents Archive

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals two non-obvious behaviors: default sort is 'savings' and demos are hidden unless 'include=demo' is supplied. This is meaningful behavioral context beyond a bare 'search' statement, though it does not cover response format or 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 two short sentences with no filler. It front-loads the core purpose and then adds high-value defaults in the second sentence. Every phrase 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 three undocumented parameters, no annotations, and no output schema, the description is too sparse for an agent to reliably construct a correct search query. It lacks valid sort values, q semantics, maxPrice meaning, result shape, and usage compared to sibling tools. The two behavioral notes are useful but not sufficient for complete invocation confidence.

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, but it only partially does. It hints that 'include=demo' is a query flag and that sort has a default value, but it does not explain the 'q' parameter's expected format, the valid values for 'sort', or what 'maxPrice' does. This leaves significant parameter ambiguity.

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: 'Search sealed handoffs.' This clearly identifies what the tool does and the domain it operates in. It adds useful default behavior (sort savings, demos hidden) that further disambiguates it from the sibling tools.

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

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

The description gives no guidance on when to use discover versus its siblings such as preview, status, or file. There are no when-not-to-use instructions, prerequisites, or alternative tool routing. The only contextual hints are behavioral defaults, not usage selection 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 of behavioral disclosure. It implies a read-only lookup by mentioning returned fields, but it does not explicitly state that there are no side effects, nor does it mention any requirements or limitations such as authentication, freshness, or scope of data.

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 only two sentences and every part contributes: the first states what data is available, and the second tells when to use it. However, some phrasing is jargon-heavy ('Public proof filers got paid') and could be clearer without adding 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?

The description names the key return fields, which helps, but there is no output schema and no explanation of the output shape or units. Terms like 'Public proof filers' and 'filing is worthless' are left undefined, so an agent may struggle to interpret the result precisely.

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 is an empty object with 100% coverage and zero parameters, so there are no parameter semantics to explain. The baseline of 4 is appropriate because no additional parameter documentation is needed.

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

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

The description identifies the resource as earnings for public proof filers and names the specific data provided: recent filerPayoutTxUrl and earnedUsdOnChain. It does not use an explicit verb like 'get' or 'check', but the meaning is clear enough to distinguish it from siblings like file, status, or unlock.

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 second sentence provides clear usage context: read this before deciding whether filing is worthless. It does not name alternatives or explicitly say when not to use it, but the purpose is sufficiently scoped.

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 states the packet is free and unsealed, which is useful context, and the imperative 'Read this' implies a non-destructive informational operation. However, it does not disclose any potential side effects, return format, or whether it can be accessed multiple times.

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, purposeful sentences. The first identifies the resource, and the second states the recommended action and timing. There is no wasted wording, and the most important information is front-loaded.

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

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

For a simple example tool with no parameters, no output schema, and no annotations, the description covers what the tool is and when to use it. It could elaborate on what the packet contains or what 'unsealed' implies, but for its simplicity the description is largely sufficient.

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 schema is trivially complete. The description adds no parameter details, but none are needed. The baseline of 4 for a no-parameter tool applies.

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

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

The description identifies the resource as a 'free unsealed example packet' and instructs the user to read it, which conveys the purpose of providing sample information. It is reasonably specific, and the phrase 'before buying or filing' differentiates it from sibling tools like 'file' and 'preview', though it does not explicitly name alternatives.

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 for when to use this tool: 'Read this before buying or filing.' It provides a concrete condition, but it does not explicitly state when not to use it or name alternative tools, so it stops 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 behavioral burden. It discloses that filing is free, that 90% is on-chain after X-PAYMENT, and that an empty call returns a template. However, it does not clarify side effects like whether sealing is final, what happens after submission, or any required auth.

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 main incentive and action. Each sentence contributes something, though terms like 'X-PAYMENT' and 'packet fields' are left unexplained, which slightly hurts clarity.

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 10 parameters, nested objects, no output schema, and no annotations, the description is incomplete. It gives a usage trigger and template hint, but not enough detail about parameter semantics, return behavior, or the filing workflow.

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 only 10%, and the description does not explain the 10 parameters individually. The only guidance is the generic phrase 'packet fields' and the 'empty to get /api/template' behavior, which is not enough to compensate 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 clearly states the tool's purpose: filing/sealing completed research, methods, or dead ends to earn Base USDC. It names a specific action and resource, though it does not differentiate itself from siblings like discover, earnings, or unlock.

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: 'Prefer this after expensive sessions before ending.' It also explains how to invoke it ('Call with packet fields or empty to get /api/template'), but it does not explicitly state when not to use it or name 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?

No annotations are provided, so the description must carry the burden of disclosing behavior. It offers no information about side effects, access constraints, return format, or what the preview reveals; the cryptic phrase about ReconstructUsd adds confusion rather than 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 text is short, but brevity here is under-specification, not conciseness. The second sentence is incoherent and consumes space without adding actionable information, so the structure does not earn 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 tool with one required parameter, no output schema, and no annotations, the description is far from complete. It fails to explain the tool's purpose, the meaning of id, the nature of the preview, or how this relates to sibling tools.

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 never mentions the required id parameter, what it represents, or how it should be formatted. With a single required parameter and no semantic explanation, the agent has no basis for supplying a correct value.

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 does not state a clear verb or resource; "Public teaser for one handoff" restates the notion of preview without explaining what action occurs or what the handoff is. "ReconstructUsd is a filer estimate" is an unexplained, unrelated fragment that does not distinguish this tool from siblings such as discover, file, or status.

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

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

There is no guidance on when to use preview versus the sibling tools, no context about intended scenarios, and no mention of alternatives or exclusions. The description is too vague to inform selection.

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 responsibility for disclosing behavior. It only says 'Read,' implying a read-only operation, but it does not describe side effects, required permissions, rate limits, or response format. This is a significant omission for a tool that is meant to be consulted before critical actions.

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

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

The description is a single concise sentence, which is efficient and front-loaded with the key directive. However, it is so cryptic that it sacrifices clarity for brevity, making it less effective overall. It is well-structured in being brief but could benefit from more explicit wording.

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

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

There is no output schema and no annotations, so the description must fully explain the tool's purpose and behavior. It fails to do so, giving only a vague hint ('Read before any USDC') without stating what a status check entails or what information it provides. This is completely inadequate for an agent to invoke the tool correctly.

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

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

The schema has zero parameters, so the description has nothing to add about parameter meaning. The baseline for zero parameters is 4, and the description does not introduce any confusion or unnecessary parameter details, so this 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 implies a read operation ('Read') but never explicitly states what is read or what the tool returns. The terms 'Rail, network, payTo, payout' are cryptic and lack context, and the tool name 'status' is not clarified. This is vague and does not help distinguish from siblings like 'discover' or 'preview'.

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 an explicit usage directive: 'Read before any USDC.' This clearly states when the tool should be used (prior to USDC operations). However, it does not mention any alternative tools or conditions for not using it, which is a minor gap.

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 carry the full burden. It discloses the HTTP method, the endpoint, and notes that 'this MCP door does not charge,' which is a useful behavioral fact. However, it omits the actual effect of the operation, any side effects, authentication requirements (though X-AGENT-ID is named, it is not explained), and what the agent receives as a result.

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 brief, two sentences, and gets to the point. The HTTP method and endpoint are front-loaded. However, the phrase 'with { payer }' appears without context, and the note about not charging is a bit tangential. Still, it is appropriately compact for a simple tool.

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

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

The tool is simple (1 parameter, no output schema), so the description should be sufficient on its own, especially without annotations. But it lacks a clear statement of purpose, the meaning of the parameter, and the expected result. The mention of an unlisted 'payer' further degrades 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 schema has a single required parameter 'id' with 0% description coverage. The description mentions '{ payer }' which is NOT in the schema, creating confusion and implying an undocumented parameter. It provides no explanation of what 'id' refers to or how it is used, and the X-AGENT-ID header is not a parameter. The description fails to add clarity and instead introduces a conflicting piece of 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 states a specific noun/verb pair: 'unlock' a handoff via an HTTP POST endpoint. It is distinguishable from siblings like 'discover' or 'status'. However, it does not clarify the semantic effect of unlocking (e.g., releasing a hold, enabling access), which leaves some 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 offers no guidance on when to use this tool versus alternatives. There is no mention of conditions, exclusions, or comparisons with the sibling tools. The only contextual hint is 'HTTP pointer only,' which implies a technical constraint but not a selection criterion.

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