AOI — Environmental Intelligence for AI Agents

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 states that 'Each capability requires a quote before execution' and 'No API key required', which are important behavioral notes. It does not detail return format or error behavior, but for a listing tool, this is sufficient. Cannot score 5 due to lack of error or edge-case handling, but it exceeds a baseline 3.

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

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

The description is three sentences, each earning its place: the first states the action and output, the second gives usage priority, and the third covers prerequisite and required auth. It is front-loaded with the core purpose. No fluff.

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

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

For a one-parameter listing tool with no output schema, the description covers the essential information: what is listed, the optional filter, the prerequisite quote, and no API key. It doesn't explain pagination or exact output structure, but the output fields are mentioned. Given the tool's simplicity, this is nearly complete. The mention of 'quote required' is crucial since all siblings are quote 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 coverage is 100% for the single optional 'domain' parameter. The description says 'Optional filter by scientific domain' and lists examples, which adds value beyond the schema's own description (which also lists examples, but the description reinforces the optional nature and gives more context). Given high coverage, baseline is 3, but the description's explicit mention of filtering and examples elevates it slightly.

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 purpose: 'List all available environmental intelligence capabilities' and specifies what is returned (capability IDs, names, descriptions, domains). It uses a specific verb 'List', identifies the resource 'environmental intelligence capabilities', and provides distinct output fields. This distinguishes it from siblings like get_capability_details and the quote functions.

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 explicitly says 'Use this first to see what AOI can do', which is a clear when-to-use instruction. It also implies it's a discovery tool before requesting quotes, and the presence of many sibling quote tools suggests this is the entry point. The description does not explicitly exclude situations, but the 'Use this first' is strong guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the financial impact (deduction on success, release on failure), error handling (INSUFFICIENT_CREDIT with top-up link), authentication requirement, and the unique credit-consuming nature. It does not mention the behavior of the idempotency key, but that is defined in the schema. Given the lack of annotations, this is a strong disclosure of side effects and prerequisites.

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

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

The description is a single well-structured paragraph that front-loads the core action, then conditions, financial behavior, output, error handling, and finally the unique credit consumption. Every sentence adds necessary information without redundancy. It could be slightly tightened, but the density is high and the logical flow is clear.

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 there is no output schema and no annotations, the description covers the essential call context: prerequisites, side effects, error handling, authentication, and the type of return ('structured intelligence with provenance'). It also explains the financial impact and the only operation that spends credits. While it could mention behavior of the idempotency key more explicitly, that is already captured in the schema. The description is sufficiently 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?

Schema coverage is 100%, so each parameter is documented. The description adds critical semantic context: the quote must belong to the agent and be valid, and input_data must exactly match the quoted request. This clarifies the relationship between parameters beyond simple type descriptions. It also implies that execution_idempotency_key affects duplicate execution, though not explicitly in text. The added context justifies a score above the baseline.

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 verb and resource: 'Execute a capability using an accepted quote.' It clearly differentiates from siblings by emphasizing 'THIS IS THE ONLY OPERATION THAT CONSUMES PREPAID CREDITS,' which sets it apart from all the quote_* and get_* tools. An agent can immediately understand what this tool does and when it applies.

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 explicit preconditions: the quote must belong to the agent, be unexpired, and input_data must match. It also states the consequence of insufficient balance and provides a top-up URL. It implies the usage sequence (get a quote first, then execute) though it doesn't explicitly name 'request_quote' as a prerequisite. This is clear and actionable, but stops short of an explicit 'use this instead of X' statement.

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

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

With no annotations, the description carries the full burden. It discloses that no API key is required and that it returns CAPABILITY_NOT_FOUND for non-existent IDs, both behavioral facts. It also lists the fields it returns. It does not explicitly state it is read-only, but the nature of a 'get' operation implies it. This is solid coverage for a simple retrieval 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 concise sentences, with the main purpose front-loaded and additional details (auth, error) efficiently included. No wasted words, perfectly structured for quick 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 tool with one parameter, no output schema, and no annotations, the description is quite complete. It covers the operation, the data returned, authentication, and error behavior. The only minor gap is a lack of detail on the exact structure of the output, but the listed fields give a reasonable overview.

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

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

The input schema has 100% coverage for the single parameter, including an example. The description adds no additional semantics beyond 'specific capability', which is redundant. Baseline 3 is appropriate since the schema already documents the parameter thoroughly.

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' and the resource 'full details for a specific capability', enumerating the specific data returned (required inputs, expected outputs, confidence level, domain). It distinguishes from siblings like discover_capabilities (listing) and quote_* tools (pricing) by focusing on retrieving details for a known capability ID.

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 when you have a specific capability ID and need its details, but it does not explicitly contrast with alternatives such as discover_capabilities for listing all capabilities or quote tools for pricing. It notes 'No API key required' and the error condition, providing some usage context, but lacks an explicit 'when to use this vs. that' statement.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds meaningful traits: no API key required, quotes are free, execution requires prepaid balance, and the overall model is quote-first. It doesn't explicitly state read-only status or rate limits, but for a simple informational 'get' tool this is adequate.

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

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

The description is compact and front-loaded with the core purpose. Each additional sentence adds distinct value—pricing model, quote workflow, cost/balance requirements, and auth—without 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?

For a zero-parameter, no-output-schema informational tool, the description fully covers what an agent needs to understand: what the tool returns, the pricing model context, cost implications, and authentication requirements. Nothing essential is missing.

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

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

There are zero parameters, so the schema needs no compensation and the description appropriately adds no parameter-specific detail. The baseline for a zero-parameter tool is 4.

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

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

Description states a specific verb and resource: 'Get the AOI commercial model description.' It further clarifies what that model is (quote-first dynamic pricing), making the tool's purpose unambiguous and distinct from siblings like request_quote and execute_quote.

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

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

The description provides clear context about when this information is relevant: before execution, in a quote-first workflow, with quotes free and execution requiring prepaid balance. It doesn't explicitly name alternatives or state when not to use the tool, but the context is strong enough for an agent to route correctly.

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, and it does disclose the key auth trait ('No API key required') and the read-style nature implied by 'Get'. It does not discuss side effects or rate limits, but for a no-argument status endpoint those concerns are minimal.

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?

One efficient sentence that front-loads the operation and result content, then adds the access note. Every word earns its place and there is no filler.

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

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

For a zero-parameter, low-complexity status tool, the description is complete: it states the purpose, names the returned content, and gives the auth requirement. No output schema is present, but the named data points are sufficient for an agent to select and successfully invoke this tool.

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

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

The tool has zero parameters, so the baseline is 4; the description correctly adds no parameter documentation because there is nothing to document. There is no gap for the schema to fill.

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 ('Get') and a clear resource ('current platform runtime status'), then names the two data points returned: active capabilities count and service health. This is distinct from sibling tools like get_capability_details, which focus on individual capability details rather than platform-wide health.

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 intended use case—checking platform runtime status—is clearly implied and the no-API-key note adds a concrete access condition. It does not explicitly contrast with alternatives, but none of the siblings offer a platform-wide status check, so there is no real ambiguity.

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

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

With no annotations, the description carries the burden itself. It discloses an auth requirement (API key) and specifies the principal data returned. It doesn't explicitly state that the operation has no side effects or describe error cases, but 'Get' plus the field list provides a clear read-only behavior for this 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?

Two tight sentences with no filler. The main purpose and return fields are front-loaded, and the auth requirement is the only extra operational note, earning 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 simple, single-parameter, no-nested-object tool with no output schema, the description gives the purpose, required inputs, and the settlement fields the agent should expect. It does not cover edge cases like missing settlements or error behavior, but that is a minor gap here.

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 only parameter already has a clear description ('The transaction to look up settlement for'). The tool description adds no new parameter-level information, so the schema carries the weight; baseline 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?

Description uses a specific verb and resource: 'Get settlement details for a transaction' and clarifies scope by naming the fields returned (captured, settled, refunded, status). This clearly distinguishes it from the quote_* siblings and other get_* tools on different resources.

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?

Usage context is implied: call it when you need settlement details for a transaction. It does not explicitly state when not to use it or name alternatives, though no settlement-specific sibling exists; the instruction 'Requires an API key' gives a prerequisite rather than 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?

No annotations are provided, so the description carries the burden. It states 'No API key required,' which is useful authentication context, and implies a read-only operation by listing factual components. However, it does not disclose response format, potential pagination, data freshness, or any rate limits. The behavioral transparency is minimal but not misleading.

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 sentence that is concise and front-loaded with the tool's purpose, followed by a list of included components. Every word adds value; no fluff or repetition. It is appropriately 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 has no parameters and no output schema, the description is nearly complete: it states what the tool provides and authentication requirements. Minor gaps include the response format (e.g., JSON structure) and any access restrictions beyond API key, but these are not critical for a simple retrieval tool. The description is sufficient for an agent to understand the tool's purpose and call it.

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 takes zero parameters, so schema coverage is trivially 100%. The description adds value by explaining what the tool returns (framework details), which is beyond the empty schema. With no parameters to document, the description adequately conveys the tool's scope.

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 retrieves the AOI trust and governance framework, listing specific aspects (security model, data classification, audit trail, zero-trust policy). It is distinct from sibling tools focused on pricing, quotes, and runtime status, so purpose is clear without needing to reference siblings.

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

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

The description implies it is a read-only informational retrieval tool for governance/framework data, but does not explicitly state when to use it vs. alternatives (e.g., get_capability_details or get_pricing_model). It mentions no API key required, which hints at authentication context, but no explicit when/when-not 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. It explicitly discloses that no execution happens, no credits are consumed, the quote is valid for 15 minutes, and an API key is required. This is strong behavioral transparency, though it doesn't mention rate limits or error behavior, which are not essential here.

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 reasonably concise, with each sentence adding value: it states the tool's purpose, the pricing behavior, the response fields, the non-execution guarantee, and auth requirements. It is front-loaded with the primary purpose and not overly verbose.

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 3 parameters, no output schema, and no annotations, the description covers the essential operational context: purpose, next step (execute_quote), safety constraints (no execution, no credits), and auth. It doesn't detail error handling or idempotency semantics, but the schema covers parameter-level details. Overall, an agent has enough to use the tool correctly.

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

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

The schema covers all three parameters with descriptions (100% coverage), so the description adds little beyond the schema. It does not explain the parameters further, only reiterating the high-level purpose. Baseline 3 is appropriate when the schema already documents the parameters.

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

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

The description clearly states the tool requests a commercial quote for capability execution, distinguishing it from execute_quote. However, it does not explicitly differentiate it from the many specialized quote_* sibling tools (e.g., quote_air_quality_assessment), which may cause an agent to hesitate between the generic and specialized variants.

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

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

It provides clear when-to-use guidance: request a quote before execution, then call execute_quote. But it does not mention alternative quote_* tools that might be more appropriate for specific capabilities, leaving the agent to infer the distinction on its own.

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