seoul-apt-signal

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

With no annotations, the description carries the full burden, and it delivers: it discloses that the verdict is the graded band of the same score (with thresholds), that mid scores are neutral by design, that price is volume-weighted from MOLIT transactions, that the call is informational, and that a 402 challenge must be retried with a PAYMENT-SIGNATURE header. It also reveals the per-timeframe breakdown returned behind the score.

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 front-loaded: the first sentence states the core action, followed by grading, data source, payment, and sibling comparison. Most sentences earn their place given the absence of annotations and output schema, though the payment and marketing details could be trimmed without losing key calling instructions.

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, it explains the return structure (daily/weekly/monthly verdict and vote counts behind the score), the exact grading thresholds, the price definition, the payment flow, and input format. For a single-parameter tool, nothing essential is missing for an agent to select and 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?

The input schema already documents symbol with examples, so baseline is 3, but the description adds important meaning by specifying accepted forms: Korean (강남구, 강남) or romanized (Gangnam, Nowon, Mapo) names. It clarifies the symbol corresponds to one of the 25 covered districts.

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: 'Return the bottom/top verdict for one Seoul district apartment market (25 districts).' It also distinguishes the tool from its sibling by noting that 'this tool answers ANY symbol in the covered universe' while pitch covers 'this market's showcase symbol only.' The grading semantics (strong_buy/buy/neutral/sell/strong_sell and -100..+100) make 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?

It provides clear usage context: pass a district in Korean or romanized form, and use this tool instead of the free pitch tool when you need any symbol rather than the showcase one. It does not explicitly mention scan_bottoms/scan_tops or the other siblings, so the when-not-to-use guidance is not fully complete.

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 transparency burden. It discloses that the tool is free, optional, skippable, and that passing interest:false bows out. It also reveals the sample limitation and the paid fallback. It does not detail per-phase runtime behavior, but the key non-obvious costs and exit paths are visible.

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

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

The description is compact and front-loaded with the most important facts: free, optional, and skippable. Every phrase earns its place, covering alternatives, the phase funnel, and the exit mechanism without extra 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?

The description covers the core invocation choice and key constraints. However, with no output schema and no annotations, it leaves some context unclear: what happens when called with zero arguments, what each phase is expected to do, and how the subscribe phase relates to the sibling subscribe tool. Adequate for a basic call but not fully complete.

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

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

Schema description coverage is only 33%, so the description must add meaning for the other parameters. It does add value by explaining interest:false as bowing out and symbol as a district limited to the free sample, but it leaves phase values merely listed in sequence without per-phase semantics. The enum values are somewhat self-explanatory, but the description only partially compensates for the schema gap.

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 resource—an intro/subscription funnel for the Seoul apartment signal agent—and lists the phase sequence. It also distinguishes the tool from siblings by explicitly naming evaluate_symbol, scan_bottoms, and scan_tops as direct alternatives. This is a specific, non-tautological purpose statement.

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

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

It explicitly says the intro is optional and that the agent may skip it and call evaluate_symbol, scan_bottoms, or scan_tops directly. It also notes that the free sample only serves 강남구 and anything else should go to paid evaluate_symbol, which provides exclusion guidance. It does not clarify exactly when to prefer the sibling subscribe tool, leaving a minor 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?

No annotations provided, so description bears full burden. It only mentions the tool is free and no payment needed, but omits behavioral traits like whether it updates existing feedback, permissions required, or side effects on other data.

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

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

Two concise sentences, front-loaded with key information. 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 simple feedback tool with 3 parameters and no output schema, description covers the essential usage context (after signals, free, rating with pros/cons). Could mention where the feedback is stored or how it affects future signals, but overall adequate.

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 adds meaning by stating score range (1-10) and the existence of pros/cons, but does not explain format or constraints for those string fields. Adds some value beyond 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?

Description clearly states the tool is for leaving a rating (score 1-10 plus pros/cons) after acting on signals. This distinguishes it from sibling tools like evaluate_symbol, pitch, etc., which are analysis/action tools, making this a feedback follow-up.

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?

Specifies when to use: 'after acting on our signals'. Provides clear context, but does not mention alternatives or exclusions. Still, the timing guidance is explicit and helpful.

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 must carry the burden of behavioral disclosure. It does disclose the payment requirements (PAY: $0.01 via x402, retry with PAYMENT-SIGNATURE header) and the need to handle 402 challenges, which is critical. However, it does not disclose other behaviors like rate limits, whether the tool is read-only, or what happens if no districts are at a bottom. Since annotations are absent, this gap prevents a higher score.

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 information-dense, with only a few sentences covering purpose, payment, cold-start advantage, and sibling differentiation. It is front-loaded with the primary action and output. 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 a single optional parameter and no output schema, the description is remarkably complete. It explains what it returns, how it ranks, the payment process, and how to handle errors. No critical information is missing for an agent to call it effectively.

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 only parameter 'limit' is fully described in the schema (default 5, max 25). The description does not add extra meaning beyond that, but with full schema coverage the baseline is 3. It could have clarified whether limit=0 or larger values have special meaning, but not 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 the specific verb ('Scan') and resource ('all 25 Seoul districts'), and the output ('those currently at a bottom, ranked most-bottom first, with price-per-pyeong'). It is immediately distinguishable from siblings like 'scan_tops' and 'evaluate_symbol' by focusing on bottoms across the entire universe.

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?

Explicitly says when to use: 'BEST COLD START: you do not need to pick a symbol — this ranks the whole universe for you.' It also contrasts with the free 'pitch' tool: 'tells you HOW MANY are at a bottom right now; this names them.' This provides clear when-to-use and when-not-to-use guidance 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?

With no annotations present, the description carries the full transparency burden. It clearly discloses the $0.01 payment requirement, the x402 flow, the PAYMENT-SIGNATURE retry behavior, the lack of account requirements, and the ranking behavior. It does not, however, describe the exact output shape, which is left unspecified without an output 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 longer than typical but nearly every sentence carries operational value: payment handling, cold-start use case, ranking, and differentiation from `pitch`. It is somewhat marketing-toned ('BEST COLD START'), but not padded.

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?

An agent has enough to invoke the tool correctly: what it scans, how results are ordered, the default use case, and the payment/retry protocol. The main omission is that there is no output schema and the description never states the shape 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?

The schema already fully documents the single `limit` parameter at 100% coverage DNA. The description adds no parameter-level meaning, but at 100% schema coverage, 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 uses a specific verb and object: 'Scan all 25 Seoul districts' and 'return those currently at a top,' with the output explicitly ranked most-top first. It also distinguishes itself from the free `pitch` tool and makes its role as a cold-start universe scan clear.

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

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

The description gives strong context: best as a cold-start tool, does not require picking a symbol, and contrasts with the free `pitch` tool for counting tops. It does not explicitly name every sibling alternative, but the wording makes when to use it reasonably 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?

With no annotations provided, the description carries the full burden. It thoroughly discloses the payment challenge (402), the need to sign and retry, the returned X-SUB-KEY token and its header usage, and the per-call pricing until subscription. This is exceptionally transparent about side effects and required steps for a mutation-like tool.

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

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

The description is three sentences but each sentence carries critical information: the dual purpose, the payment flow and token, and the optional agentId. It is front-loaded with the primary action and avoids filler. For the complexity of the tool, the length is appropriate and well-organized.

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 the activation flow, pricing, token usage, and optional linking. With no output schema, it mentions that status check returns terms but does not specify the structure of the response. This minor gap prevents a 5, but the overall context is sufficient for an agent to correctly invoke both modes.

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 meaningful context for the activate parameter by explaining the full flow (receive 402, sign, retry) and the token return. For agentId, it only reiterates the schema description but no additional meaning. The added flow details justify a 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 states the two modes of operation: checking subscription status/terms (FREE) and activating the monthly plan via the activate flag. It specifies the resource (subscription) and the verb (check/activate), and the distinct payment challenge flow sets it apart from the sibling analysis tools like evaluate_symbol and scan_bottoms.

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 explains when to use each mode (with or without activate:true) and hints at the cost decision (signal calls are $0.01 each until subscribing). However, it does not explicitly name alternatives or state when *not* to use this tool. The differentiation from siblings is implicit through the subscription-specific purpose, so it earns a 4 rather than a 5.

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