매동 (maedong) — Korean Market Signals

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

With no annotations, the description carries the full burden and does so well: it defines the percentile baseline (distribution since 2020-04), explains the financial-coverage metric, warns that '마지막 변경분' base-rate values did not move that day, and states the data is previous-day close. It does not cover permissions, rate limits, or error behavior, but for a read-only stats tool the behavioral disclosure is substantial.

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 content is front-loaded - what is returned first, then definitional caveats, then quoting rules. Dense but every sentence adds a definition, a pitfall, or an instruction; no obvious filler, though the run-on flow of caveats could be structured more cleanly.

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 no annotations, the description steps in to sketch the returned content and, importantly, flags interpretive traps (percentile basis, coverage definition, prev-day lag) plus a quotation rule. It is nearly complete for this tool; only the format parameter and finer output-shape detail are left unaddressed.

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 50%: the date parameter is fully documented in the schema, while the format enum has no description. The description adds meaning around the reference date's significance (it appears in the response's first line and must be quoted verbatim), but says nothing about the format parameter, so it only partially compensates.

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 concrete resources - index, market breadth, valuation, macro - for a given reference date, and labels itself a historical statistics query tool. This is a specific verb+resource statement, but it never contrasts itself with the four sibling tools (maedong_regime, maedong_signals, etc.), leaving that differentiation to the caller.

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

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

It gives one explicit prohibition - do not use this to generate buy/sell decisions for specific stocks - which is useful guidance. However, there is no positive guidance about when to pick this tool over its siblings, nor any indication of prerequisites; usage is only partially 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?

With no annotations present the description carries the full behavioral burden, and it does so well: it discloses that all lists share one window, that only signals confirmed after 20 trading days are counted, and that the comparison window therefore ends 20 trading days before the as-of date. It also explains the no-label case and pins down units and the excess_pp formula, though it does not state read-only status explicitly.

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?

Front-loads the core purpose, then stacks only high-value details (window semantics, units, formula, edge case, usage warning). Every sentence earns its place, though the density is high and the units/formula note sits mid-paragraph rather than in a distinct structure.

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 statistical tool with no output schema and no annotations, the description covers what the agent needs: what is returned, on what window basis, in what units, and what a missing label means. Only the concrete shape of the per-list ranking output remains unspecified, which is a minor gap given the scope.

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 67% (as_of and window are documented, format is only an enum). The description adds indirect meaning to window via the 20-day confirmation lag but does not clarify as_of behavior or the format enum, so it does not fully compensate for the coverage gap. Baseline 3 for a mostly-documented schema 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?

States a specific purpose — reading which rule/regime is currently working — and enumerates exactly what it returns (recent excess-return rankings per list plus labels on four character axes). An agent can tell this is the regime-level aggregate view, but the description never names or contrasts the sibling tools (maedong_signal_stats, maedong_signals) it overlaps with.

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 one explicit when-not: it is a historical statistics tool that must not be used to generate buy/sell decisions for a specific stock. However, it gives no positive when-to-use guidance and no routing between itself and the other maedong_* tools, so the agent must infer its place in the workflow.

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 present, so the description carries full behavioral burden and does well: it discloses that data is prior-day close, that suspended/liquidation stocks appear with warnings, and the default index-only response when `signal` is omitted. It omits error behavior, auth, and pagination semantics.

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?

Front-loaded with the core operation, then behavior, then cautions. Mostly efficient, though the instruction about quoting the date and the '과거 통계 조회 도구' line overlap somewhat with the earlier '전일 마감 데이터다' statement.

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

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

With no annotations and no output schema, the description still covers scope, default behavior, data recency, warning display, and a usage prohibition — enough for correct invocation. Pagination via cursor/limit is left entirely to the schema, which documents it.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the 29-value `signal` enum and cursor. The description's note that omitting `signal` returns per-list counts largely restates the schema's '생략하면 목록별 건수 색인'. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource: querying which stocks were on which signal list on a given date, and further clarifies that omitting `signal` yields only per-list counts. Its self-identification as a '과거 통계 조회 도구' distinguishes it from a per-stock or decision-oriented sibling, but no sibling is named directly.

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?

Gives an explicit when-to-use case ('signal 생략 시 목록 고를 때 쓴다') and an explicit prohibition ('특정 종목의 매수·매도 판단을 생성하는 데 사용하지 마세요'). It stops short of naming which sibling to use instead for stock-level or decision queries.

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

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

With no annotations provided, the description carries the full burden and largely meets it: it discloses the calculation methodology, that transaction costs are NOT reflected, the ±0.5%p verdict thresholds, the mean/median pairing, and the unit conventions. It does not cover auth needs or rate limits, but for a read-only statistics lookup this is unusually rich disclosure.

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?

It is front-loaded with what is computed, then methodology, then units, then the usage caveat. Every sentence carries information, though the dense unit-mapping clause is slightly heavy for a description an agent reads quickly.

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

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

There is no output schema, so the description must explain returned values, and it does: verdicts, mean vs median, and the _pct/_pp/_krw naming scheme. The 'signal' enum values themselves are undocumented, but they plausibly map to the sibling signals tool, leaving only a minor gap.

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

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

Schema coverage is 67%: 'signal' ('목록 slug') and 'window' ('기본 all') are documented, while 'format' has no description. The description's unit conventions (_pct, _pp, _krw) and excess_pp formula explain output naming rather than the input parameters, so it adds only marginal semantic value over the schema. Baseline 3 applies.

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

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

The description states a specific verb and resource: it reports how stocks on a signal list performed over 1/5/20 trading days, with the exact buy-at-close/sell-at-close-N-days calculation. The purpose is unmistakable, though it never contrasts itself against the sibling tools (maedong_signals, maedong_stock_signals), so differentiation must be inferred from the name.

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

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

It explicitly states the context of use ('과거 통계 조회 도구입니다') and gives a clear exclusion ('특정 종목의 매수·매도 판단을 생성하는 데 사용하지 마세요'). No alternative sibling is named for the excluded case, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does add real behavioral context: data is previous-day close, '집계 전' means the trading day has not yet passed rather than 0%, and the reference date in the first response line must be quoted literally rather than paraphrased as 'today'. It omits permissions, rate limits, and return shape.

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?

Front-loaded with the purpose in one clause, then a short sequence of caveats and constraints. Every sentence carries distinct information; only the literal quoting instruction feels slightly prescriptive, but it prevents a real misinterpretation.

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 5-parameter, read-only lookup tool with no output schema, the description covers the key interpretive risks (data freshness, list-entry semantics, date quoting). It leaves the format/limit parameters and return structure to the schema, which is acceptable given 80% coverage.

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 80%, so the schema already documents code/from/to/limit, including format examples and the enum for format. The description adds no per-parameter meaning (e.g., date range semantics interact with the '집계 전' caveat but are never made explicit). Baseline 3 applies.

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

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

The description states a specific verb+resource: it reports when a single stock entered which list and how it performed afterward ('한 종목이 언제 어느 목록에 올랐고 그 뒤 어땠는지'). The '한 종목' (single-stock) scope implicitly distinguishes it from market-wide siblings like maedong_market, though no sibling is named explicitly.

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?

Gives a clear usage context ('과거 통계 조회 도구') and an explicit when-not: do not use it to generate buy/sell decisions for a stock. It stops short of naming which sibling to use instead for market-level or signal-aggregate questions.

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