mfc_ca_putJournals

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

With no annotations provided, the description carries the full burden of disclosing behavior. It states that this is a mutation ('帳簿書き込み' = ledger write), that it performs a full replacement (overwriting the entire journal), and that user approval is required. This goes beyond a generic 'updates' and gives the agent a realistic sense of side effects and authorization needs, though it doesn't mention failure modes or potential data loss 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?

One concise Japanese sentence with no filler. The core verb is front-loaded, and the key qualifiers (full replacement, ledger write, user approval) are packed efficiently. Every word earns its place, making it easy to scan and understand.

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 essential behavioral aspects (update, full replacement, approval) but leaves out critical context: what 'id' means, what happens to omitted optional fields during full replacement, and what the response looks like (no output schema exists). Given the nested journal object and two required parameters, an agent would need more detail to call it correctly without guessing.

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 50% (journal has a description, id does not). The tool description adds no parameter guidance whatsoever—it doesn't explain that 'id' refers to the target journal's identifier or clarify the full-replacement semantics for missing journal fields. The description in the schema for 'journal' exists, but the tool itself provides zero parameter disambiguation, so it fails to compensate for the 50% coverage 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 states the action ('仕訳を更新します' = 'updates journals') and adds crucial detail ('全置換API' = full replacement API), which distinguishes it from creating (postJournals) or deleting (deleteJournals) operations. The verb+resource combo is unambiguous and immediately conveys the tool's role.

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 for updating existing journals but provides no explicit comparison to alternatives like postJournals for creation or deleteJournals for removal. It does clarify that it's a full-replacement API, hinting it's not for partial updates, but lacks any 'use this when...' or 'instead of...' guidance. The 'requires user approval' note is a constraint, not a selection guideline.

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