Apex (smartapex.uk) AI Component Card Store

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

Annotations already provide readOnlyHint=true. The description adds behavioral context: the tool never returns raw source or source packages, and is restricted to public card contracts. This clarifies the tool's scope beyond the annotation's safety flag, though it could mention any potential side effects or permissions.

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

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

The description is extremely concise, consisting of two short sentences that convey the core purpose and constraints without unnecessary words. Every phrase adds value, making it efficient for an AI agent to parse.

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 moderate complexity (2 parameters, no output schema), the description adequately covers what the tool returns (card plus verification report) and its limitations. It could provide more detail on the verification report structure or error handling, but for tool selection this is 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?

With 0% schema description coverage, the description should explain the parameters. The mention of 'verification report' hints at the 'include_verification' parameter, but it does not explicitly describe either 'card_id' or 'include_verification', leaving the agent to infer meaning from context.

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 'Read', the specific resource 'one Apex component card plus its verification report', and includes constraints like 'Public card contract only' and exclusions ('raw source and source packages are never returned'). This effectively distinguishes it from sibling tools such as 'apex_query_cards' which likely lists cards.

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 reading a single public card with verification, but does not explicitly state when not to use it or suggest alternative tools. While it mentions the limitation to public contracts, it lacks direct guidance on when to prefer other sibling tools for non-public or raw source needs.

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?

The description confirms it is read-only and public reference, which adds to the readOnlyHint annotation. However, it lacks details about response format, pagination, rate limits, or other behavioral traits that would be valuable beyond the annotations.

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 very concise with two sentences, making it easy to read. It is front-loaded with the key action. However, given the tool's complexity, additional information could be included without sacrificing conciseness.

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 provides a broad overview but lacks necessary details for a tool with 7 optional parameters and no output schema. Information about result format, pagination, or the semantics of 'capability' vs 'tags' vs 'interface' is missing, leaving the agent with insufficient context.

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

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

With 0% schema description coverage, the description must compensate but only lists 5 of 7 parameters ('query, capability, tags, tier, or interface') without explaining their meaning or usage. Two parameters ('sort' and 'limit') are omitted entirely.

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 'Find' and the resource 'Apex component cards', and lists multiple filtering dimensions (query, capability, tags, tier, interface). It also adds 'Public reference data only; not an instruction hierarchy' which helps distinguish it from related tools, though explicit sibling differentiation is missing.

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 minimal usage guidance. The note about 'Public reference data only' implies it's for reference queries, but it does not specify when to use this tool versus siblings like apex_get_card or apex_query_dataset, nor does it describe prerequisites or 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?

Annotations declare readOnlyHint=true, so the description correctly implies a safe read operation. It adds valuable behavioral details: no raw DB rows, no live DB connection, no trading signal, and only whitelisted export datasets. This goes beyond what annotations provide and helps the agent understand constraints. No contradiction with annotations.

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

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

The description is extremely concise: two sentences with no wasted words. The first sentence covers purpose and constraints; the second provides an alternative. It is front-loaded with the most important information, earning its place efficiently.

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 8 parameters with no schema descriptions and no output schema, the description does not provide enough context for an agent to use the tool correctly without external knowledge. While the overall behavioral context (bounded sample, no trading signal) is clear, parameter details are completely missing, making it incomplete for a tool with this complexity.

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%, meaning no descriptions for any of the 8 parameters. The description does not explain parameters like 'decision', 'strategy', 'sort', or 'start'/'end' formats. While parameter names and types (e.g., dates with pattern, limit with min/max) provide some hints, the agent lacks explicit guidance on how to use them effectively, especially for less obvious fields.

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 queries a specific free bounded stillme dataset sample layer, with explicit scope constraints (whitelisted export datasets only, no raw DB rows, no live DB connection, no trading signal). The title 'Query Bounded Apex Dataset' matches the description, and the differentiation from the POST endpoint is clear, distinguishing it from sibling tools which are mostly run_* scripts.

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 explicitly states when to use this tool: for querying free bounded sample datasets. It also provides a clear alternative for larger slices: use POST /v1/datasets/{name}/query with an Agent Passport. However, it does not explicitly mention other sibling tools like apex_query_cards or the run_* tools as alternatives, though the context of 'query' vs 'run' is implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds specific behavioral traits: 'DATA ONLY, read-only, no HMAC required; no route discovery, source reads, or network access.' This significantly expands beyond annotations, clarifying what the tool does NOT do.

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: the first states the action and inputs, the second lists behavioral constraints. No redundant words. Information is front-loaded and every sentence earns its place.

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

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

For a tool with no output schema, the description covers input semantics, safety, and excluded actions. It mentions 'bounded' but does not explain what bound means, and maxItems 500 is not stated. Overall, adequate but has minor gaps.

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

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

Schema coverage is 0% and both parameters are unimformative arrays of objects. The description adds meaning by calling them 'before/after endpoint lists', which helps the agent infer purpose. However, it does not explain the structure of the object items or constraints like maxItems 500, leaving 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 clearly states the tool runs an 'API contract diff' over 'before/after endpoint lists', naming the specific operation and its inputs. It is distinct from sibling tools like apex_run_agent_release_readiness_gate, which serve different purposes.

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 context for usage: 'DATA ONLY, read-only, no HMAC required; no route discovery, source reads, or network access.' This helps the agent know it's safe and permissionless, but it does not explicitly compare to alternative tools or state when not to use it.

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

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

Annotations already indicate readOnlyHint=true. The description adds 'read-only, no HMAC required, no network access' and explicitly states it does not echo raw values, providing additional behavioral context beyond annotations.

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 efficiently conveys purpose, key features, and constraints without any superfluous words. Every element adds value.

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 single parameter and no output schema, the description covers the input and behavioral constraints well. However, it lacks explicit detail on the output format, leaving some ambiguity about the structure of the returned profile.

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?

With 0% schema description coverage, the description partly compensates by mentioning 'tabular rows' and profiling aspects, but it does not fully detail the expected structure of each row object or the exact input constraints beyond max items.

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 profiles tabular rows, specifying the type of analysis (shape, nulls, types, numeric ranges, sensitive-name hints) without echoing raw values. It distinguishes itself from siblings which are for different analyses like card queries or license checks.

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 no guidance on when to use this tool versus alternatives among siblings. No explicit when-to-use or when-not-to-use context is given.

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

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

Annotations already mark readOnlyHint=true and openWorldHint=false. The description adds value by detailing specific constraints: no HMAC required, no build, no registry lookups, no network access, and lists the exact lint rules. This provides context beyond the annotations without contradiction.

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 efficient sentence that front-loads the action and lists checks and constraints. Every word adds value; 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?

Given the single input parameter, no output schema, and annotations, the description fully covers the tool's purpose, behavior, constraints, and input semantics. It provides all necessary context for correct invocation.

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

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

With only one parameter ('dockerfile') and 0% schema description coverage, the description compensates by stating 'supplied Dockerfile text', clarifying that the input is the raw text content. This adds meaning beyond the schema's type string and maxLength, but does not elaborate on formatting or examples.

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 identifies the tool as a static best-practice lint for Dockerfile text, listing specific checks like unpinned bases, curl-pipe-shell, etc. This distinguishes it from sibling tools (e.g., financial analysis agents, secret scanner) by being a dedicated Dockerfile linter.

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 explicitly states when to use (DATA ONLY, read-only) and what it does not do (no build, no registry lookups, no network access). This provides clear guidance on appropriate use cases and contrasts with potential alternatives that might perform builds or network operations.

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?

The description adds significant behavioral context beyond annotations: 'DATA ONLY, read-only, no HMAC required; embedded policy table only, no registry lookups or network access.' No contradiction with annotations.

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, concise and front-loaded with the core purpose. Every part adds value without 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?

No output schema is provided, and the description does not describe the return format beyond classification buckets. Given the tool's simplicity, this may be sufficient, but agents might benefit from knowing the exact structure of the response.

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 does not explain individual parameters (policy, licenses, dependencies). It mentions 'supplied dependency licenses' but fails to map to schema, leaving the agent uncertain about parameter usage.

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 it classifies dependency licenses into PASS/REVIEW/BLOCK buckets using SPDX identifiers. It is specific and distinguishes from sibling tools which cover different domains.

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 indicates it's a read-only, release gate tool with no network access, implying use in CI for license checks. It does not explicitly state when not to use or name alternatives, but context is moderately clear.

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?

Beyond annotations (readOnlyHint: true), the description reveals behavioral traits: secret values never leave the redactor, no network access, and data-only processing. This adds valuable context but could further detail what happens to the data (e.g., no persistence).

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 output, and ends with constraints. Every word adds value, no 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?

Given no output schema, the description omits the exact output format (e.g., structure of severity, patterns, samples). It adequately covers safety and constraints but leaves uncertainty about return value shape.

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?

With 0% schema description coverage, the description should explain the two parameters (logs and text). It mentions 'supplied logs' but does not clarify the role of 'text' or the constraints on each. This lack of parameter guidance hampers correct invocation.

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: redact and summarize logs into severity, repeated failure patterns, and short safe samples. It also adds distinguishing constraints like 'DATA ONLY, read-only, no HMAC required, no network access', which helps differentiate from 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 provides clear context for when to use the tool (for supplied logs, data-only, read-only) and implicitly excludes use cases requiring network or HMAC. However, it does not explicitly state alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds value by enumerating specific actions it avoids (deploy, publish, read files, call CI) and confirms no HMAC required. This provides concrete behavioral assurance beyond the annotation flags.

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

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

The description is extremely concise: two sentences. The first states the core action, the second enumerates constraints. Every word earns its place; no redundancy or 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?

Given 10 parameters, no schema descriptions, no output schema, and nested objects, the description should explain input structure and return behavior. It only states the tool evaluates booleans/evidence, but does not describe what the gate returns (pass/fail?), how errors are reported, or how to use the results. The tool's purpose is clear but operational context is insufficient.

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?

With 0% schema description coverage for 10 parameters, the description carries full burden but only vaguely mentions 'caller-supplied booleans/evidence'. It does not explain the role of parameters like 'build', 'tests', 'checks', 'rollback', etc., leaving the agent with insufficient semantic understanding to fill them correctly.

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 runs a release readiness gate that is permissionless, bounded, and read-only. It uses a specific verb 'run' and resource 'release checklist gate'. However, it does not explicitly differentiate from sibling tools like apex_run_btc_gate, missing the chance to distinguish its scope.

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 context through phrases like 'DATA ONLY, read-only, no HMAC required' and 'never deploys, publishes, reads files, or calls CI', indicating it is safe and non-destructive. However, it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among the 13 sibling 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?

The description adds context beyond the readOnlyHint annotation: permissionless, bounded, no HMAC required, and specifies exactly what is returned (redacted findings, hashes, line numbers) and what is not (raw secrets). No contradiction with annotations.

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 sentence with zero wasted words. Every clause adds value: action, constraints, usage context, and output guarantee. Front-loaded with the core action.

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 nested parameters and no output schema, the description covers the primary behavior and output type but lacks details on file object fields, when to use text vs. files, and the exact structure of findings, hashes, and line numbers.

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%. The description maps parameters to 'text/file content' but does not differentiate the two parameters (text string vs. files array with name/path/text/content fields) or explain constraints like maxLength or optionality. Minimal added meaning.

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 'Run the allowlisted permissionless bounded secret scanner over supplied text/file content', which is a specific verb+resource (run secret scanner) and distinguishes from sibling tools like apex_run_agent_api_contract_diff or apex_run_empyrical_metrics.

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 scanning secrets in text/file content with safety guarantees ('no HMAC required', 'never raw secret values'), but does not explicitly state when to use it vs. alternatives or any 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?

The description adds significant behavioral transparency beyond annotations, detailing that the tool is permissionless, requires no HMAC, no network access, no orders, no wallet/account access, and is read-only. Annotations already set readOnlyHint=true, and the description reinforces and expands on this.

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 very concise, using two sentences to convey purpose and safety constraints. It is front-loaded with the main action. However, it could be more structured by separating the purpose from the behavioral notes.

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?

Despite having no output schema, the description does not explain what the tool returns. The enum values for function imply different outputs (e.g., factor_weights, factor_returns), but no details are given. For a complex tool with five parameters and nested object inputs, the description lacks essential information about return values, leaving the agent guessing.

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%, and the description provides no explanation for any of the five parameters (period, options, records, function, quantile). While parameter names and the enum for function offer minimal semantics, the description adds no value beyond the schema's bare structure. For a tool with 0% coverage, the description should compensate but fails to do so.

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 runs an alphalens-style factor research wrapper over supplied factor rows, specifying it's a pure TypeScript reimplementation of selected alphalens-reloaded routines. It distinguishes from sibling tools like apex_run_backtrader_engine or apex_run_strategy_gatekeeper by emphasizing its read-only, data-only nature.

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 for when to use the tool (permissionless, bounded factor research) and explicitly states what it does not do: 'DATA ONLY, read-only, no HMAC required, no network, no orders, no wallet/account access.' However, it does not mention alternatives or explicitly state when not to use it.

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

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

Annotations declare readOnlyHint=true, which the description echoes with 'DATA ONLY, read-only'. The description adds significant behavioral context: it is 'allowlisted permissionless bounded', a 'pure TS reimplementation', and specifies security aspects (no HMAC required, no network, no broker adapters). This goes beyond what annotations provide, though it could mention resource usage or concurrency limits.

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

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

The description is extremely concise: two sentences that front-load the core purpose and then list key constraints. Every word adds value, no repetition, and the structure is clear. It is an exemplary model of conciseness.

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 4 parameters (including nested objects) and no output schema, the description covers safety and scope well but omits several important details: it does not explain what the tool returns (output format), the structure of the 'bars' or 'strategy' objects, any performance considerations, or error handling. The lack of output schema means the description should bear more burden for completeness, which it only partially does.

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%, meaning the schema provides no parameter descriptions. The description mentions 'OHLCV bars' and 'declarative strategy rules', which partially explains the 'bars' and 'strategy' parameters, but it does not mention 'initial_cash' or 'costs' at all. Given the system has 4 parameters with nested objects, the description fails to adequately compensate for the lack of 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 clearly states the verb ('run'), resource ('backtrader-style single-asset backtest engine'), and inputs ('OHLCV bars and declarative strategy rules'). It further distinguishes itself from siblings by listing what it does not do (no broker adapters, no network, etc.), 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 good context on when to use this tool: it is a 'pure TS reimplementation of a narrow OSS backtrader subset' and is 'data only, read-only'. It also explicitly states what it does not support (no orders, no wallet access), which helps an agent decide against using it for trading or wallet interactions. However, it does not explicitly compare to sibling tools like apex_run_strategy_gatekeeper or apex_run_deflated_sharpe, so the guidance is strong but not exhaustive.

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

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

Annotations already provide readOnlyHint=true; the description adds that it is 'Pure calculation, DATA ONLY, read-only, no HMAC required, no orders, no wallet/account access', going beyond annotations to clarify safety and authentication requirements.

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 concise sentences, front-loading the core purpose and adding no redundancy. Every sentence provides essential 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 description explains the tool's return values (ALLOW/BLOCK plus move_pct and drop threshold) and its read-only nature, but lacks details on output structure (e.g., data types) given the absence of an output schema, leaving some ambiguity.

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 does not individually explain the three parameters (current_price, reference_price, threshold_pct). While it mentions output calculation, it fails to clarify how threshold_pct is used, offering little added meaning 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 it is an 'Advisory market-regime gate' that returns ALLOW/BLOCK plus move_pct, contrasting with sibling tools like regime_hurst or kelly_sizer by focusing on a price-based gate check.

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 gate checks based on price thresholds and notes it is 'Not trading advice', but does not explicitly state when not to use it or list alternatives among siblings.

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?

The description adds significant transparency beyond the readOnlyHint annotation by stating 'DATA ONLY, read-only, no HMAC required, no source release, no orders, no wallet/account access.' This confirms the behavioral constraints and scope of operation.

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 with two sentences, each adding value. The first sentence states purpose, the second lists key behavioral traits. No unnecessary words.

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 covers overall purpose and constraints but omits parameter documentation and return value information. With no output schema and 4 parameters, the agent lacks critical details 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?

With 0% schema description coverage, the description must compensate but fails to mention any parameters. No explanation is provided for 'returns', 'n_trials', 'confidence', or 'trial_sharpe_variance', leaving the agent without guidance on how to use them.

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 'Run' and the specific resource 'deflated-sharpe diagnostic', distinguishing it from sibling diagnostic tools like apex_run_btc_gate or apex_run_kelly_sizer. However, it could be more descriptive about what the diagnostic does (e.g., computes deflated Sharpe ratio).

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 notes the tool is 'permissionless' and 'data only', implying safe usage, but does not provide explicit guidance on when to use this tool over siblings. No direct comparison or exclusions are given.

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

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

Annotations already indicate readOnlyHint=true. The description goes beyond by stating no HMAC required, no orders, no wallet/account access, adding behavioral context. No contradiction with annotations.

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 concise sentences. The first sentence states purpose and outputs, the second clarifies constraints. No wasted words.

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 no output schema. The description explains inputs and outputs but lacks details on calculation logic or range of outputs. Parameter descriptions would improve 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?

Schema description coverage is 0%. The description mentions inputs implicitly (consecutive_losses, recent_net_pnl) but does not explain their meaning, units, or how they affect the output. It adds minimal value over the plain 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 the tool returns size_multiplier, cooldown_sec, and severity based on a loss streak. It uses a specific verb 'Run' and identifies the resource 'Dynamic Penalty Advisory'. This distinguishes it from sibling tools that perform different analyses.

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 explicitly says it is a pure calculation, read-only, no orders, no HMAC required, and not trading advice. This provides clear context for when to use it. However, it does not explicitly compare to alternatives like apex_run_kelly_sizer for different sizing scenarios.

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

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

Annotations already indicate read-only. Description adds safety context: 'DATA ONLY, read-only, no HMAC required, no network, no orders, no wallet/account access.' No contradiction with annotations.

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 efficiently communicate purpose and behavioral traits. Front-loaded and without redundancy. Could slightly improve by hinting at key parameters.

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?

Adequate for a read-only calculator with annotations, but no output schema and no description of return values or error conditions. Missing completeness for a complex metric tool.

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

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

Schema description coverage is 0%. Description only mentions 'supplied returns' but does not explain period, risk_free, or annualization parameters. The description adds little meaning beyond parameter names.

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

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

Clearly states the tool runs an empyrical-style metrics calculator over supplied returns, with specific mention of being a pure TS reimplementation of OSS empyrical 0.5.5. Distinguished from siblings by name and description.

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?

Implied usage for computing empyrical metrics, but no explicit guidance on when to use this tool versus specific siblings like apex_run_deflated_sharpe or apex_run_kelly_sizer. No when-not or alternatives 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?

The description adds meaningful behavioral context beyond the readOnlyHint annotation by explicitly stating 'no HMAC required', 'no orders', 'no wallet/account access', and 'not financial advice'. These details help the agent understand the tool's safety profile and limitations. No contradiction with annotations.

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, consisting of three sentences with essential information front-loaded. It avoids verbose explanations but could benefit from a more structured breakdown of parameters or output.

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

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

The tool has no output schema, and the description does not explain what the tool returns (e.g., a single number, a recommendation object, or an error). Given the mathematical nature and lack of output schema, the agent needs more clues about the return format to use the result 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?

With 0% schema description coverage, the description should explain all parameters, but it only mentions 'win rate and average win/loss facts', covering the three required parameters (win_rate, avg_win, avg_loss). It does not describe the optional parameters (regime, confidence, max_fraction), their meaning, or their impact on the calculation.

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 it performs 'Advisory fractional Kelly sizing math' from win rate and average win/loss facts, which is a specific verb+resource. However, it does not explicitly differentiate itself from sibling tools like apex_run_deflated_sharpe or apex_run_regime_hurst, leaving the agent to infer when Kelly sizing is appropriate versus other calculations.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, contraindications, or compare with sibling tools. The only contextual note is 'DATA ONLY, read-only, no HMAC required', which is more about safety than usage scenarios.

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

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

Annotations already declare readOnlyHint=true. The description adds valuable details: 'DATA ONLY, read-only, no HMAC required, no network, no orders, no wallet/account access' and mentions output declares data_as_of. No contradictions with annotations.

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 very concise at three sentences. The key information (what it does, constraints, output hint) is front-loaded with no redundant 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?

For a simple tool with 3 parameters and no output schema, the description adequately covers purpose, behavior, and constraints. It hints at output format but does not fully describe return values. Overall, it is sufficiently complete given the low complexity.

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

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

Schema coverage is 0%, meaning the description should explain parameters. It only says 'over supplied calendar/date parameters' without elaborating on each parameter's meaning, format, or constraints. The schema provides enum and patterns, but the description adds minimal semantic 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 clearly states the tool runs a pandas market calendar wrapper for specific calendar/date parameters, using a verb ('Run') and specific resource ('pandas_market_calendars 5.4.0 calendar wrapper'). It distinguishes from sibling tools by being data-only and read-only.

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 this tool is for market calendar queries but provides no explicit guidance on when to use it versus other apex_run_* sibling tools. It lacks when-not-to-use or alternative tool references.

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?

Beyond annotations (readOnlyHint=true), the description adds critical behavioral details: 'no HMAC required, no plots, no network, no orders, no wallet/account access'. This fully discloses security and interaction boundaries, exceeding annotation 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 a single, dense sentence that packs essential information (library, version, input, constraints) without fluff. It is front-loaded with the action and efficiently conveys the tool's scope.

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 is fairly complete given annotations and schema constraints, but it lacks output specification (e.g., what a tear sheet result looks like). No error handling or resource limits are mentioned. Adequate but not fully self-contained.

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

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

Schema coverage is 0% with no parameter descriptions. The description only mentions 'supplied dated returns' vaguely, failing to explain the required structure (date-return objects) or the optional periods_per_year constant. Minimal compensation for low coverage.

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 runs pyfolio-reloaded tear-sheet core on dated returns, specifying the exact library and version (0.9.9). It distinguishes from siblings by emphasizing 'bounded', 'permissionless', and 'data only' constraints, making its 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 strong usage context: 'DATA ONLY, read-only, no HMAC required, no plots, no network, no orders, no wallet/account access.' This tells when to use (for financial return analysis) and what not to expect, but lacks explicit comparison to sibling tools like apex_run_empyrical_metrics.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=false. The description adds concrete behavioral guarantees like no HMAC, no network, no orders, no wallet/account access, reinforcing safety. No contradictions.

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, front-loaded sentences with no redundant words. Purpose and constraints are clearly stated.

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 classifier with annotations covering safety, the description is mostly complete but lacks parameter explanations for lower/upper, which are needed for correct invocation without trial and error.

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

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

Schema coverage is 0%, so description must explain parameters. It only mentions 'supplied prices' but fails to describe 'lower' and 'upper' thresholds. This leaves critical parameter meaning unclear.

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: a pure regime classifier over prices returning Hurst estimate and label. It distinguishes itself from siblings by emphasizing 'data only, read-only, no network, no orders, no wallet/account access'.

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 explicitly defines when to use: for purely computational regime classification with no external dependencies or side effects. It also specifies what it does not involve (HMAC, network, orders, wallet/account), guiding the agent away from 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?

The description reinforces the annotation 'readOnlyHint: true' by stating 'DATA ONLY, read-only, no HMAC required, no orders.' It adds that no authentication is needed and it performs no side effects, which is valuable context beyond the annotations.

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 (one sentence plus clarification). However, it compresses many details and could benefit from structured explanation of the gate logic. Slight lack of completeness for the sake of brevity.

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 11 parameters, 7 required, no output schema, and no description of return value, the description is insufficient. It does not explain how the advisory gate produces a result, what the output type is, or how the min parameters interact with the statistics.

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?

With 0% schema coverage, the description carries full burden. It lists key statistics (CI lower bound, effect size, slippage improvement, sample depth, p-values) which map to some parameters, but omits important ones like alpha, min thresholds, and multiple_testing_mode. This provides partial but incomplete guidance.

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 it is a 'composite advisory gate' over specified statistics, and adds that it is read-only and does not place orders. This distinguishes it from write tools, but it does not explicitly contrast with sibling analysis tools like apex_run_deflated_sharpe, which may perform similar evaluations.

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 provided on when to use this tool versus alternatives. The description does not mention conditions for selecting this gatekeeper over other analysis tools, nor does it specify prerequisites or 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?

Beyond the readOnlyHint annotation, the description adds behavioral details such as 'pure calculation, DATA ONLY, read-only, no HMAC required, no orders, no wallet/account access, not trading advice.' This provides useful context that is not available from annotations alone.

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 unnecessary words. The first sentence front-loads the purpose and outputs, and the second adds safety clarifications. Every sentence earns its place.

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

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

Given the simplicity of the tool (pure calculation, no output schema) and the annotations providing readOnlyHint, the description covers the essential behavioral aspects. However, it could be more complete by explicitly describing the return value format or conditions.

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 description mentions 'seconds_open and max favorable excursion' which maps to seconds_open and likely mfe_bps, but it does not clarify timeout_sec or mfe_threshold_bps. With 0% schema description coverage, the description partially compensates but leaves ambiguity for half 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 performs an advisory exit check for stagnant positions, returning HOLD or EXIT_TIMEOUT based on seconds_open and max favorable excursion. It distinguishes from siblings by emphasizing it's a pure calculation, data-only, read-only, and not trading advice.

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 checking stagnant positions but does not explicitly state when to use this tool versus alternatives like apex_run_deflated_sharpe or apex_run_kelly_sizer. No when-not-to-use guidance is provided.

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

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

No annotations are provided, so the description carries full burden. It indicates a write operation and safety warnings, but does not disclose reversibility, side effects, response format, or error handling. For a mutation tool, more behavioral detail is needed.

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?

Concise with two sentences front-loading the core action. The list of forbidden items is a bit long but still efficient. No 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?

Given 12 parameters and no output schema, the description lacks context for most fields, the meaning of 'usage review', and expected response. Only the receipt type logic and forbidden content are covered, leaving the tool incomplete for effective use.

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

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

Schema coverage is 0%, so description must compensate. It only explains receipt_id and agent_id context, while 10 other parameters (e.g., card_id, tool_id, usefulness_score) are undocumented, leaving significant 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 clearly specifies the verb 'Submit' and the resource 'safe usage review tied to an existing Apex verification receipt', and distinguishes it from sibling tools like query or run 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?

Provides explicit conditional guidance on when agent_id is needed (verified receipts) versus not (permissionless bounded receipts), and lists prohibited content. However, it does not explicitly state when to use this tool over alternatives or mention prerequisites.

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