Maatsii

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds process-level context such as using actually fetched intervals, setup verification via playbook text, and an optional intermarket section. This is useful but does not fully disclose output behavior or operational details.

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 with multiple dash-separated clauses. It packs in a lot of information but is not particularly concise or front-loaded in a scannable way. The core idea is clear, but the structure could be improved.

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 input parameters and no output schema, the description explains the framework's components and end goal. However, it does not clarify how the tool is meant to be invoked or what kind of response/result is expected, leaving some ambiguity for an agent.

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

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

The input schema has no parameters, so there are no parameter semantics to explain. The description does not need to compensate for missing schema details, and the baseline for 0 params 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?

The description clearly identifies the tool as an 11-section MTF LinReg analysis structure and states its purpose: to produce a full TA with actionable levels. It is specific enough to distinguish it from sibling tools like chart_map or get_chart, though it does not explicitly name a sibling.

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 constructing a full technical analysis, but it gives no explicit guidance on when to choose this tool over alternatives. There are no references to sibling tools or conditions that would trigger its use, leaving the agent to infer usage.

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 destructiveHint=false, and the description adds important context: chart IDs are non-contiguous, the map includes aliases and derived tickCharts inventory, and the precedence rule about printed headers. This goes beyond the structured annotations and helps an agent understand behavior and limitations.

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 information-dense. Every sentence adds value: the authoritative scope, the content of the map, the non-contiguity caveat, the routing use case, and the header precedence rule. 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?

For a static read-only map tool with no parameters and no output schema, the description covers all necessary information: what data is included, how to use it, and a critical behavioral caveat. There is nothing an agent needs to call it correctly that 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?

The tool has zero parameters, so there is no schema detail to compensate for. The description explains what the returned data contains (the map and its components), which is sufficient for a parameterless tool.

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

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

The description clearly states the tool's purpose: providing an authoritative map of chart IDs to symbols/timeframes/groups, including aliases and tickCharts inventory. It uses a specific verb ('map') and resource, and differentiates from sibling tools like maatsii_get_chart by focusing on routing symbols to IDs.

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 the tool: 'use this to route a symbol to the right ids.' It also provides a critical caveat that the printed header wins over the map, which guides correct usage. However, it does not mention explicit alternatives or when not to use it, leaving a slight gap.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so this is clearly a safe, non-mutating reference tool. The description adds useful context about what content the guide covers, but it doesn't describe behavioral details such as whether the guide is static, how it is returned, or whether it could change under the openWorldHint annotation.

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 front-loads the core subject ('LinReg fan geometry') and then enumerates the key topics. It is slightly long and packed with clauses, but every part contributes substantive information and nothing is wasted.

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 that this is a parameterless guide with no output schema, the description is largely complete: it covers the fan elements, statistical rails, label convention, confluence, and slope alignment. It could be slightly stronger by explicitly stating what the tool returns or how to request more detail, but as a reference guide description it covers the essential ground.

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 and schema coverage is 100%, so there are no parameter semantics to explain. The description correctly focuses on content rather than parameter details, matching the baseline for a parameterless tool.

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

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

The description identifies a specific resource — LinReg fan geometry — and states the tool's purpose: teaching how to read fan structure including rails, parity, mean-reversion, label convention, confluence zones, and slope alignment. It clearly differentiates this from sibling tools like maatsii_reading_guide and maatsii_analysis_framework by focusing on fan-specific interpretation.

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 by defining the topic and content area ('how to read fan structure'), so an agent can infer this is the right choice when fan interpretation is needed. However, it never explicitly states when to use this over siblings, nor does it mention any exclusions or alternative 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?

Annotations already carry readOnlyHint=true, destructiveHint=false, and idempotentHint=false. The description adds meaningful behavior beyond that: returns a JPEG inline plus a JSON metadata block, the api.maatsii.com url has a unique cachebuster (fresh per call, consistent with idempotentHint=false), and it warns that the printed chart title is ground truth. This is rich, non-obvious behavioral disclosure with no 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?

Three dense sentences, each earning its place: purpose/selector, return format, and interpretation guidance. The core purpose is front-loaded, and the reading instructions are appended without redundancy. No filler or restating of what the schema already says.

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 moderate in complexity and has an output schema, so return-value details need not be repeated. What an agent needs to invoke it correctly — required selector, return shape, and how to interpret the chart — is all present. Minor gaps (error behavior for an invalid id, meaning of 'group') are non-critical 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?

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds concrete ticker examples (NQ_100T, BTCUSD, PLTR), clarifies the uniqueness of the cachebuster, and affirms the inline JPEG default behavior, which enriches the parameter understanding beyond the schema alone.

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

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

The description opens with a specific verb-resource pair: 'Get ONE fresh Maatsii chart by id (c1..c200) or ticker', naming exact selectors and concrete examples. It clearly distinguishes itself from the other get_* siblings by emphasizing it returns chart imagery for a single chart, not a map, concept, group, or setup.

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 context for use is explicit: you need a fresh chart image for a known id or ticker, and the description tells the agent exactly what to do with the result (vision the image, trust the printed title, read prices off the right axis). It also routes the price-reading subtask to the maatsii_reading_guide sibling. It lacks explicit 'when-not-to-use' exclusions against sibling chart tools, but the context is 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral detail: it lists valid concept names and explains the fallback for unknown concepts, which helps the agent anticipate the tool's response beyond the schema.

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, information-dense sentence that front-loads the core purpose and includes a compact list of known concepts. It is concise with no filler or redundant phrasing.

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 read-only tool with one parameter, the description covers its purpose, the list of valid inputs, and the behavior for unknown inputs. No output schema exists, but the described 'few sentences' response is clear enough for an agent to invoke it 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 description coverage is 100% — the only parameter 'concept' is clearly described with examples. The description does not add extra parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool explains a Maatsii concept in a few sentences, listing specific concept names to disambiguate scope. It distinguishes itself from sibling tools like maatsii_get_chart or maatsii_get_setup by focusing on conceptual explanation rather than data retrieval.

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: use it to get a short explanation of a named concept, and it also documents the unknown-concept fallback behavior. It does not explicitly mention when not to use it or name alternatives, but the purpose is distinct enough that usage 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?

Discloses several non-obvious behaviors beyond annotations: every chart is inlined with no server cap, metadata always lists the whole group even when a subset is requested, and the image_mode max_images behavior. It also gives an important domain note about the RATES group. This goes well beyond the readOnlyHint and openWorldHint 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 long but information-dense. Every clause carries practical value, though some ideas repeat (e.g., 'EVERY chart in the group is inlined by default' and 'there is no server image cap'). Front-loading the core function helps, but the length is justified by the tool's complexity.

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 five parameters and non-trivial domain semantics, this description is remarkably complete. It specifies return format (JPEG inline + JSON metadata), aliases, grouping caveats, default behavior, and parameter usage. The presence of an output schema further reduces the need to document return fields, yet the description still covers the essential output content.

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?

Although the schema already documents all parameters at 100% coverage, the description adds substantial meaning: explains the group aliases, the effect of ids (subset with metadata still full), the difference between image_mode values, and the optional max_images hint. This is a model of compensating for schema gaps and enriching parameter understanding.

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?

States a specific verb and resource ('Get FRESH charts for every chart in a group'), distinguishes from single-chart tools by emphasizing 'the REAL non-contiguous ids' and describes exactly what is returned (JPEG inline plus JSON metadata). This clearly differentiates it from sibling tools like maatsii_get_chart.

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 rich context on how to use the tool: accepts friendly aliases, explains the YIELDS vs CREDIT grouping, and details parameter choices (ids, max_images, image_mode). While it doesn't explicitly name alternative tools or state when not to use it, the usage context is clear enough for an agent to decide 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?

Beyond the readOnly/destructive annotations, the description discloses important behavior: accepted id formats, the fact that only active setups work (64 active setups, 45 Fan + 19 Tick), error cases, and the critical caveat that 'Catalog direction is not the trade side.' This adds substantial context an agent needs.

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

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

The description is compact yet dense: it covers purpose, input semantics, output contents, usage guidance, and a key caveat in just three sentences. No filler or repetition; 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?

Even without an output schema, the description enumerates exactly what the returned data includes. Given the tool's simplicity (one parameter) and the rich behavioral context provided, nothing critical is missing for an agent to invoke it 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 description coverage is 100%, so the baseline is 3. The description enriches this by listing concrete accepted formats ('#19', '19', 'T1', 't1') and clarifying that ids outside the active library error. This goes beyond the schema's simple example.

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

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

The description opens with a specific verb and resource: 'Get the full public playbook for ONE active setup by id', clearly distinguishing this from listing or matching tools. It also names the returned components (catalog card plus logic/entry/confirmation/etc.), leaving no ambiguity about what the tool does.

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

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

The description states a clear use case: 'Use it to verify a candidate against the chart before citing it.' It also explains error behavior for invalid ids. However, it does not explicitly mention when NOT to use this tool or point to a specific alternative like maatsii_list_setups for browsing all setups.

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 destructiveHint=false, so the description carries a lighter burden. It adds meaningful context: 'card' versus 'full' output behaviors, the direction field is the pattern's native side not the trade side, and that 'strengthTier is an ID-band label, not live chart state.' These are clarifying notes beyond what annotations provide and help an agent interpret results correctly.

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 of about three sentences. It front-loads the core function (blacklisting all setups) and then packs in useful details (total counts, detail modes, filtering options, and critical constraints). While it is dense, there is no filler; every clause contributes meaning, and it remains understandable.

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

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

With no output schema, the description carries the responsibility to explain what the tool returns. It covers 'full' (once each setup's playbook fields are enumerated) and 'card' (catalog fields only), and explains the semantics of the 'direction' and 'strengthTier' fields. It also states which filters are supported and the applicability constraint across chart intervals. For a read-only listing tool, the description provides sufficient context for an agent to invoke it and interpret results 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 60% (3 of 5 parameters have descriptions in the schema). The description compensates for this by explaining 'type' (FAN/TICK/ALL) and 'direction' (native side vs trade side), which are missing from the schema. It also explains 'detail' exactly as the schema does, and mentions the 'timeframe' constraint in the context of tick charts. This added explanation is helpful for 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 begins by stating the exact action and scope: 'List all 64 active LinReg setups (45 Fan -series + 19 Tick T-series).' This specifies a clear verb ('list') and a well-defined resource ('setups') with precise counts and types, distinguishing it from sibling tools like maatsii_get_setup which retrieves individual setups. It also introduces the 'detail' concept, which is central to the tool's output differences.

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

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

The description provides clear usage context: it is for listing/browsing all setups, with an explicit hint that 'detail: card is a lightweight catalog for browsing.' It also gives a substantial caveat that TICK setups and tick-native Fan #34 apply only on 100T/1000T tick charts, which guides when to filter by timeframe appropriately. However it does not explicitly address alternatives like maatsii_get_setup for a single result, nor does it directly say when not to use this tool.

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

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

Beyond the readOnly/destructive annotations, the description discloses important runtime behavior: it may return best null on empty or thin input, never invents a setup, returns qualitative fit labels plus playbook text, and the catalog direction label should be ignored. This is meaningful behavioral context.

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 dense but mostly earns its length: it front-loads the optional-hint warning, then gives eligibility rules and output caveats. However, it is a single wall of text; structured bullets or shorter sentence groups would make the guidance easier to scan and apply.

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

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

With no output schema and a nested vision_features object, the description compensates well by covering null results, output labels/playbook, the direction-label caveat, and gate rules. The main omission is the exact return container shape (single best match vs list), especially because max_results suggests multiple candidates may be returned.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by linking timeframes to actual read intervals and TICK/Fan eligibility, tying groups_read to fetched groups and the vol-gated setup #78, and explaining that vision_features includes raw_vision_text with natural language and negation handling. Max_results relies on the schema, which already describes it well.

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 names a specific action and resource: cross-checking vision_features against the 64-setup active library. It also explicitly contrasts itself with the client-driven matching and with maatsii_get_setup, so an agent can distinguish it from siblings without extra digging.

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 opens by marking itself as an optional hint and telling the agent not to lead with it, which is direct usage guidance. It also states when extra parameters are required (timeframes for TICK eligibility, groups_read for setup #78) and names the verification sibling maatsii_get_setup.

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 provide readOnlyHint=true, openWorldHint=true, destructiveHint=false, but the description still adds significant behavioral context: it specifies that no VRVP, VWAP, or volume-profile data is printed on the template, and that the mid label is 'EQ'. This disclosure of what the tool does NOT provide goes beyond the annotations and helps the agent set expectations.

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 well-structured: it leads with the core purpose, then lists precise facts, and ends with what to avoid. Each sentence adds distinct information without repetition or filler. It is appropriately sized for a zero-param tool.

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

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

The description is complete for a zero-param tool: it explains the chart-format conventions and the boundaries of what the tool addresses. The lack of an output schema is mitigated because the tool is essentially a reference/guideline rather than a data-producing function. Nothing necessary for calling it correctly 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?

The tool has zero parameters, so schema coverage is effectively 100%. The description doesn't need to add parameter-specific semantics, and it doesn't attempt to. The baseline of 4 for zero-param tools applies here; no further information is needed.

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

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

The description clearly states what the tool does: it teaches how to read a Maatsii chart, with specific, unambiguous facts (price on the right axis, black last-price tag equals header Close, fan labels are <TF> <type>). It distinguishes itself from siblings by listing what is NOT done (no OCR, no pixel math, no black-box hunting), making the purpose concrete and grounded.

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 when this guide is applicable (when reading a chart) and implicitly discourages using OCR/pixel methods as substitutes. However, it does not explicitly mention when to prefer this tool over siblings like maatsii_fan_guide or maatsii_chart_map, nor does it state any conditions that should NOT trigger this tool. The usage context is implied but not made explicit.

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