kairos-signal

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does not explicitly state that the operation is read-only, does not consume credits, or any side effects. While 'check' implies non-destructive, the lack of explicit disclosure is a significant gap, especially since purchase_data and topup_credits exist as siblings.

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 wasted words. It front-loads the core purpose ('Check your remaining credit balance') and adds a concise usage tip in the second sentence. Perfectly sized for the tool's simplicity.

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 tool with one parameter and no output schema, the description covers purpose and usage. However, it lacks explicit behavioral transparency (read-only, no credit deduction) and does not clarify the response format. These gaps make it minimally complete but with room for improvement.

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 already provides 100% coverage for the single parameter 'api_key' with its description. The tool description adds no additional information about the parameter, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Check' and the specific resource 'remaining credit balance', which uniquely identifies this tool among siblings like topup_credits and purchase_data. It leaves 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 provides clear usage context with 'Use after purchases to see remaining credits.' This tells the agent when to invoke the tool, though it does not explicitly mention alternatives or when not to use it. This meets the criteria for clear context without 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, the description carries the full burden. It discloses the free tier record limit and that additional access requires purchases or credits, which is behaviorally useful. However, it does not mention what happens when limits are exceeded, whether authentication is required, or what the response format looks like—gaps that are significant for a data query 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 comprised of three short, information-dense sentences with no fluff. It leads with the action and then provides the critical business constraint, making it easy to parse quickly.

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?

Considering the tool has three parameters, no annotations, and no output schema, the description covers the core purpose, key parameters (limit/offset), and a key business rule (free tier). It stops short of describing the return payload or pagination behavior, but this is acceptable for a straightforward query tool with well-documented parameters.

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%, with each parameter already described clearly (e.g., limit's max for free tier, offset's meaning, dataset's example). The description's mention of 'limit/offset' adds minimal extra meaning beyond the schema. It does tie the limit to the free tier rule, which is a slight enhancement, but overall the schema already does most of the work.

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 'Query records from a dataset with limit/offset', which uses a specific verb and resource, clearly differentiating it from siblings like list_datasets (which lists dataset names) and get_stats (which computes statistics). This is a clear and distinct 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 provides practical usage context by specifying the free tier limit (10 records per query) and hinting that more extensive access requires purchasing products or topping up credits. It indirectly points to the need for related tools such as purchase_data or topup_credits, but does not explicitly name them or state when NOT to use this 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 provided, the description carries the full burden of behavioral disclosure. It implies a read operation but does not state whether it is safe, what side effects might occur, whether it is expensive, or what the response contains. This is too minimal to inform an agent of important behavioral traits.

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 short sentence, which is concise, but it is under-specified. It does not waste words, but it also does not provide enough substance to be considered well-structured. It earns a midpoint score because brevity is achieved at the expense of usefulness.

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 has no output schema and no annotations, the description needs to explain what the returned statistics are and how they might be used. It does not. The description is incomplete for an agent to understand what will happen when invoking 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?

The tool has 0 parameters, so there is no parameter schema to elaborate. Per the baseline for zero-parameter tools, the description need not add parameter details. The description is acceptable for a parameterless 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 says 'Get aggregate statistics from the databases', which uses a specific verb ('Get') and a resource ('statistics'), but 'the databases' is ambiguous and does not clarify which databases or what kind of statistics. It does not distinguish from sibling tools like list_datasets, which also deal with databases, so the purpose remains somewhat vague.

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 this tool versus alternatives. The description does not mention any conditions, prerequisites, or exclusions. Contextual signals show siblings like check_balance and list_datasets, but the description never explains how get_stats fits among them.

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 mentions the return of a 'cryptographic provenance proof,' but does not state side effects, authentication requirements, rate limits, or what happens if the record_id is not found. The tool's read-only nature is implied but not explicitly confirmed.

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 that communicates the essential information without redundant phrases. It is front-loaded with the action and resource, and 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?

The tool is relatively simple with one parameter, but there is no output schema, so the description should explain the structure of the returned proof. It only says 'cryptographic provenance proof,' which is vague. It also lacks context about error handling or the nature of 'current datasets,' leaving gaps 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 already describes record_id as 'Record ID to get provenance for' with 100% coverage. The description does not add any additional meaning or clarify format or constraints beyond that. The baseline score of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: to return a cryptographic provenance proof for a record ID. It uses a specific verb ('Return') and resource ('record ID'), and the mention of 'current datasets' adds scope. This distinguishes it from sibling tools like verify_footprint, which likely verifies a proof rather than generating one.

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 usage guidance is provided. The description does not state when to use this tool versus alternative tools like fetch_dataset or verify_footprint, nor does it mention any exclusions or prerequisites. The only hint is 'from current datasets,' which implies a limitation but does not guide 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 provided, the description carries the full burden. It discloses the read-only nature (listing) and adds the behavioral trait 'Free to browse' (no cost). It also indicates the response includes record counts, which is beyond a simple list. However, it doesn't mention other response details like pagination or metadata fields.

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

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

The description is two short sentences: the first states the core function, and the second provides a list of content categories. There is no redundancy, and it is front-loaded with the main purpose.

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 zero-parameter tool with no output schema, the description is sufficiently complete. It explains what is listed, includes record counts, and gives examples of dataset categories. It could optionally mention the response format, but that is not necessary given the tool's simplicity.

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 coverage is 100% by default. The rubric sets a baseline of 4 for 0 params, and the description does not need to add parameter-specific 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 clearly states the specific action ('List all available datasets') and the resource (datasets) with the additional detail 'with record counts.' This distinguishes it from siblings like fetch_dataset and purchase_data, which imply different 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?

The description implies usage for browsing datasets by saying 'Free to browse' and enumerating content categories, but it does not explicitly state when to use this over siblings or when not to use it. No alternatives are mentioned.

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 fully disclose behavioral traits. It doesn't explicitly state that browsing is read-only, nor does it mention authentication requirements, pagination, or return format. The pricing context is useful but insufficient for full 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 two sentences, front-loaded with the core purpose, and then provides examples and a usage hint. Every sentence adds value with no redundancy, making it both concise and 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?

For a parameterless listing tool, the description covers the content, pricing, and when to call it. The lack of an output schema means return-format details are missing, but the tool's simplicity and the concrete examples make it adequately complete for an agent to 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 tool has zero parameters, so there is nothing to explain. The baseline score for 0-parameter tools is 4, and the description adequately describes the tool's behavior without needing parameter details.

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: 'Browse all purchasable products with prices in credits'. It provides a list of example product categories, making it unmistakable what the tool does. This distinguishes it from sibling tools like list_datasets or purchase_data.

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 an explicit usage cue: 'Call after register_agent to see what to buy.' This establishes when to use the tool. It also enumerates included product types, helping agents understand relevance. However, it doesn't explicitly contrast with alternatives like purchase_data or check_balance.

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 full responsibility for behavioral disclosure. It only implies credit deduction with 'with your credits' and mentions the api_key prerequisite. It fails to state irreversibility, what happens on insufficient credits, failure modes, or the response format. This is a significant transparency gap for a mutation/purchase 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 focused, front-loaded sentences. The first states the action, the second provides useful product enumeration and auth guidance. No filler 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 simple 2-parameter tool with no output schema or annotations, the description covers the product list and authentication prerequisite adequately. However, it omits what the tool returns (e.g., order ID, success message) and does not mention error scenarios, leaving a minor completeness 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 schema already describes both parameters with 100% coverage, including examples for product_key (dag_pro, mcp_unlimited). The description's list of product categories adds mild context but does not fundamentally enhance 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 clearly states a specific verb and resource: "Buy a product with your credits." It distinguishes this tool from siblings by being the actual purchase action, and it lists example products, making its scope unmistakable.

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: you need credits and an api_key from register_agent. It does not explicitly say 'use list_products to browse items' or 'use topup_credits if short on credits,' but the context is sufficient to infer when to use this tool. No exclusions are mentioned, preventing 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 important behavioral traits: no credit card or human required, no Stripe, credits work immediately, and the tool grants an API key. This goes beyond the schema and gives the agent confidence about side effects. It doesn't explicitly mention whether registration is reversible or if there are any limitations, but the core behavior is well disclosed.

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

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

The description is concise and front-loaded with 'START HERE'. Each sentence adds value: what you get, what's not needed, immediate usability, and next steps. No redundancy or 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 is simple with only 2 required parameters and no output schema. The description explains the purpose, benefits, and next actions, making it complete for an agent to use the tool correctly. It also situates it within the broader workflow by referencing list_products.

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% since both parameters (email, agent_name) have descriptions. The tool description adds no additional parameter details beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: self-register as an AI agent to receive free credits and an API key. It uses a specific verb ('Self-register') and resource ('AI agent'), and the 'START HERE' tag distinguishes it from sibling tools like topup_credits and purchase_data.

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 says 'Call this first' and instructs to call list_products next, providing clear sequencing and context for when the tool should be used. It also explains what the credits can be used for, giving the agent enough context to decide when registration is needed.

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 behavioral disclosure. It states the operation (adds credits), mentions that USDC requires a tx_hash, and notes that Stripe generates a checkout link for a human operator. This gives some insight into the side effects and payment workflows, but doesn't mention details like processing time, fees, or what happens on failure. Adequate but not rich.

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, well-structured sentence that packs in the purpose, trigger, and two payment methods without wasting words. Every clause adds relevant 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 relatively simple, with 4 parameters and no output schema. The description covers the essential context: when to use it, how to pay, and what information to provide. It doesn't describe the response format, but given the simplicity and lack of output schema, this is not a major gap. It also implies that tx_hash is required for USDC, which a human might need to know.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining that tx_hash is for USDC payments and that the Stripe method produces a checkout link for humans. It also clarifies the conditional nature of tx_hash ('provide tx_hash' for crypto payments), which is not obvious from 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 clearly states the tool's purpose: 'Add credits' when the free balance runs out. It identifies the resource (credits) and provides a precise trigger condition, distinguishing it from sibling tools like purchase_data (buying data) and check_balance (checking balance).

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

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

It gives a clear usage trigger: 'when your $5 free balance runs out.' It also explains the two payment methods (USDC vs. Stripe) and when each applies. It doesn't explicitly mention alternatives like 'use purchase_data for data purchases,' but the context 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 must carry the full burden of behavioral disclosure. It only mentions the output type (SHA-256) and target (dataset or record), but does not disclose side effects, authentication requirements, rate limits, or error behavior. The agent cannot infer whether this is a purely read-only operation or if it has other implications.

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 that front-loads the key action (Return) and specific resource (SHA-256 cryptographic verification). There is no filler or redundancy, making it easy to parse quickly.

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 absence of an output schema, the description should clarify what the agent can expect in response, but it only states the return type cryptographically. It also leaves ambiguity between 'dataset or record' and the required parameters (both dataset and record_id), and provides no context on how this differs from get_zk_provenance or when it should be used.

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 100%, so both parameters are well-documented: 'dataset' is the dataset name and 'record_id' is the record ID to verify. The description adds minimal value, merely saying 'dataset or record' without explaining how the parameters interact or what formats are expected. It does not enhance the schema's clarity.

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 the tool returns SHA-256 cryptographic verification for a dataset or record, which is a specific verb+resource combination. It is clear but does not explicitly differentiate from the sibling tool get_zk_provenance, which may also provide verification or provenance. Still, the description is unambiguous about the core 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?

There is no guidance on when to use this tool versus alternatives like get_zk_provenance, nor any prerequisites, exclusions, or context for selection. The description only defines the action, leaving the agent without decision support.

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