screen_journals

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

With no annotations, the description must disclose behavior itself. It discloses that detection is not evidence of fraud and that it returns a sorted list. However, it does not state that the operation is read-only/non-destructive, does not describe pagination or truncation via the 'top' parameter, and gives no detail on the output structure (e.g., risk scores, matched rules). The caveat is useful, but more behavioral context is missing.

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 primary action and outcome, then a critical caveat. There is no redundancy or filler; every sentence earns its place. The caveat is placed at the end, which does not obscure the main purpose.

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 complex nested options object and no output schema, the description does not describe the return format (e.g., whether it includes risk scores, rule triggers, or just the sorted journals). It also does not mention that it accepts both simple and detailed journal formats (though the schema covers this). The description is adequate for a basic understanding but lacks details needed for an agent to 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 description coverage is 100%, so the baseline is 3. The description mentions applying rules to journal data but does not elaborate on the 'top' or 'options' parameters beyond what the schema already documents. It adds no additional semantic value to 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 applies all rules to journal data, sorts by risk score descending, and returns results. It positions itself as a primary screening tool distinct from sibling tools like check_balance or detect_duplicates, which are more targeted. The phrase '仕訳データに全ルールを適用し' makes the action and resource explicit.

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 context as a '一次スクリーニング' (primary screening) for narrowing what humans should review first, implying it is the initial step. However, it does not explicitly mention when to avoid using it or direct the agent to specific siblings for narrower analyses (e.g., detect_duplicates for duplicate checks). Guidance is implied but not explicit.

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