get_value_stock_screen

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

Annotations already declare the safe read-only/idempotent/closed-world profile, and the description goes well beyond that: cache-only with no API call, supported plan tiers, REIT exclusion rationale, and the nullability contract for margin_ratio/margin_date (null on Free/Light or when no margin data) plus the daily-vs-weekly margin date cutover. These are behavioral traits an agent cannot recover from 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?

Content is front-loaded with the core screen before the criteria and alternatives, and almost every sentence adds information. The one weak spot is the keyword-list sentence ('Use for 年安 割安 高配当 好決算, 年安圏の割安高配当株...'), which is partly retrieval stuffing rather than specification, making the block longer than strictly necessary.

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 10-parameter, composite-criteria screener this covers purpose, the full AND-logic, exclusions, plan gating, sibling routing, and parameter semantics; return values need not be explained because an output schema exists. An agent has everything needed to invoke it correctly and interpret empty results (criteria are conjunctive).

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%, so the description carries the full burden and does so: all 10 args are explained with bounds and defaults, and it adds semantics the schema lacks — 'exclusive' bounds, 'Net-loss stocks (EPS<=0) never match', 'Negative-book stocks (BPS<=0) never match', the NxFDivAnn>FDivAnn priority rule, and the meaning of require_profit_increase and disc_months.

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 first sentence states a specific verb (screen) and resource (value stocks near 52-week low with high forward yield and profit-increase forecast), and the criteria sentence spells out the exact AND-composition. It distinguishes itself from siblings by naming get_valuation_ranking, get_dividend_yield_ranking and detect_52w_high_low as single-criterion alternatives, so an agent can separate it without opening any schema.

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?

Explicit routing is given: 'For a single criterion use get_valuation_ranking / get_dividend_yield_ranking / detect_52w_high_low', plus a when-not case ('REITs are excluded... use get_dividend_yield_ranking for REIT yields') and the overlap note that it appears as the value_screen section of get_market_briefing. The trigger phrasings (Japanese and English) also anchor when to reach for it.

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