agentix

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

With no annotations, the description carries full behavioral disclosure. It usefully reveals that polling continues until 'settled' or 'disputed' and that the delivered output and verification result appear at that point. However, it does not mention side effects, authorization requirements, rate limits, or behavior for non-terminal statuses.

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 with no filler. The primary action is front-loaded, and the important terminal-status detail is placed second. Every word contributes meaning.

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 polling tool with no output schema and no annotations, the description delivers the core mechanism but leaves gaps: possible non-terminal statuses, return shape, and error behavior are undisclosed. It is minimally adequate but not 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?

The schema has 0% description coverage and only defines order_id as a required string. The description does not explicitly document the parameter, but the overall phrase 'an order's status' gives enough context to infer that order_id identifies the order to poll. This is marginal semantic 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 uses a specific verb ('Poll') and resource ('an order's status'), making the tool's core function immediately clear. It does not explicitly compare itself to siblings like purchase_skill or submit_skill, but the domain of order status checking is distinct enough that an agent can tell it apart.

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 use this tool versus alternatives, when polling is appropriate, or how it fits into an order lifecycle. The description states what it does but not when an agent should choose it over other 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?

With no annotations provided, the description carries the full burden. It discloses a key limitation: the output schema is reduced to field names and the exact output format is only available after purchase. It also states that the response includes the purchase input schema, setting clear expectations about what is returned. This is significant behavioral context beyond a simple 'get'.

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, with the primary purpose front-loaded and no extraneous words. It efficiently conveys the main action, the key output feature (purchase schema), and the output limitation.

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 single-parameter lookup tool with no output schema, the description covers the essential purpose, the included purchase schema, and the output format limitation. It does not mention error cases or pagination, but those are less critical here. The sibling tools provide surrounding context, making this sufficiently 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?

The schema description coverage is 0%, so the description must compensate. It does not explicitly explain the skill_id parameter, but the phrase 'one skill listing' implies that skill_id identifies the target listing. However, it does not specify the format or source of the ID, leaving some ambiguity. Given there is only one parameter and its purpose is fairly obvious, 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 verb ('Get'), the resource ('one skill listing'), and adds a specific detail about including the purchase input JSON Schema. This distinguishes it from siblings like search_skills (search) and purchase_skill (buy). 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 implies the tool is for retrieving details before purchasing, but it does not explicitly state when to use it versus alternatives (e.g., use this before purchase_skill, or use search_skills for discovery). There is no exclusion guidance or explicit condition, leaving the agent to infer the appropriate 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?

No annotations are provided, so the description bears full burden for behavioral disclosure. It does a commendable job: it discloses the validation, the two-step payment mechanism (invoice return plus optional direct wallet-push), the best-effort and fire-and-forget nature of NWC payment, and the explicit note that escrow release is driven by invoice payment detection, not the wallet-push. It also warns about checking the response fields and paying manually if needed. The only minor gap is that it doesn't describe the exact response structure beyond the two fields mentioned, but given no annotations, this is strong coverage.

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 (about 150 words) but every sentence earns its place. It front-loads the core action and the key validation steps, then details payment handling, then clarifies escrow release. The structure is logical: purpose → validation → payment mechanics → important caveat. It's not overly verbose; the length is justified by the complexity of the purchase flow with optional wallet integration.

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 (4 parameters, nested input object, optional payment integration, and no output schema), the description is remarkably complete. It covers validation (schema and spend cap), required parameters beyond the minimal shape, payment process (invoice and optional wallet push), response fields to check, and escrow release behavior. An agent has all necessary information to invoke the tool correctly and interpret outcomes, even without an output schema.

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 75% (3 out of 4 properties have descriptions, with agent_wallet_connection having a clear description). The description adds significant context beyond the schema: it explains why api_key and input are required (for spend-cap enforcement and skill execution) and clarifies the purpose of agent_wallet_connection (to request payment). The description also clarifies the semantics of 'input' (must match the skill's input schema). This adds meaning beyond the raw JSON schema, especially for api_key (why it's needed) and input (why it's often 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 clearly states the tool's purpose: 'Purchase a skill.' It goes beyond a simple verb+resource by detailing the full flow: validation against listing schema and spend cap/allowlist, generation of a Lightning invoice, escrow holding, and payment handling. This distinguishes it from siblings like check_order_status (which checks status) and submit_skill (which likely submits/creates), 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 provides explicit usage context and excludes alternatives implicitly. It explains when to use this tool (to purchase a skill after selecting one) and exactly what to check afterward (wallet_payment_requested/wallet_payment_error and manual payment if needed). It also clarifies the behavior regarding escrow release versus wallet-push success, which is a critical 'when' constraint. While it doesn't explicitly name sibling tools, the contrast is clear from the described flow—no other sibling is referenced, but the unique responsibilities of this tool vs. others are implicitly clarified.

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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It goes beyond the schema by explaining the hybrid keyword/category match, semantic search when configured, and that tags are folded into the same keyword search as query with no dedicated tags field. This gives agents useful behavioral nuance, though it omits output shape and price filter 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?

Three concise sentences, front-loaded with the primary purpose and then adding only relevant behavioral detail. No filler or repetition of schema content.

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

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

With no annotations and no output schema, the description covers the search and matching behavior but leaves gaps: how results are returned, whether pagination exists, and exactly how max_price_sats filters. It is adequate for choosing the tool but not fully self-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?

Schema description coverage is 50%, so the description must partially compensate. It does clarify tags semantics and mentions category matching, but max_price_sats is left completely unexplained. This is a partial compensation, not a complete one.

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 ('Search') and resource ('Agentix skill catalog by capability'), making the tool's purpose immediately obvious. It also distinguishes itself from sibling tools like get_skill, purchase_skill, and submit_skill by describing catalog search rather than retrieval, purchase, or submission.

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 finding skills by capability, so a natural use case is clear. However, it does not explicitly state when to prefer this over sibling tools like get_skill, nor does it mention any exclusions or alternative routing.

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

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

With no annotations present, the description carries the full burden and does so well: it discloses that the operation is not actually available, that it returns a structured 'not available' response, and that it writes nothing. This is precisely the behavioral context an agent needs.

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, front-loaded with the intended purpose and immediately followed by the critical availability caveat. Every word contributes useful 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 tool that is currently a stub, the description gives the key operational facts: it is not available, returns a structured 'not available' response, and has no side effects. It is slightly thin on the exact shape of that response and on parameter expectations, but those are less important given the tool's non-functional status.

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% across 5 parameters, and the description adds no parameter-level meaning. It never explains fields like price_sats, input_schema, output_schema, or how they relate to the listing. Even for a stub endpoint, the description does not compensate for the missing schema 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 states a clear verb and resource: 'Submit a new skill listing for sale.' It also immediately distinguishes this from the sibling tools (search, get, purchase), and the 'NOT YET AVAILABLE' warning clarifies that the tool is a non-live stub.

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 explicit context about when not to use this tool: the flow isn't live and calling it writes nothing. It does not, however, name alternatives or specify a positive scenario for calling it, so it falls just short of full usage guidance.

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