update_record

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it's a mutation operation (updates records), explains the two identification methods (record_id or updateKey), specifies field value format requirements ('各フィールドは { "value": ... } の形式で指定します'), and provides concrete examples. It doesn't mention authentication requirements or rate limits, but covers the core behavioral aspects well for a mutation 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 appropriately front-loaded with the core purpose and usage guidance, but includes two lengthy JSON examples that could be condensed. While the examples are helpful, they make the description quite long. Every sentence earns its place, but the structure could be more concise by summarizing the examples or moving them to a separate section.

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 mutation tool with no annotations and no output schema, the description provides substantial context: clear purpose, usage guidelines, parameter explanations, and behavioral details. It covers the essential aspects of how to use the tool effectively. The main gap is the lack of information about return values or error conditions, but given the complexity of the tool and the absence of output schema, it's reasonably 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 100%, so the baseline is 3. The description adds significant value beyond the schema by explaining the relationship between record_id and updateKey ('レコードIDまたはupdateKeyのいずれかを指定して更新できます'), providing detailed examples of the fields parameter structure, and clarifying that updateKey requires duplicate-prohibited fields. This goes well beyond what the schema descriptions provide.

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 tool's purpose: 'kintoneアプリの既存レコードを更新します' (updates existing records in a kintone app). It specifies the exact resource (existing records) and operation (update), distinguishing it from sibling tools like create_record, upsert_record, and update_record_status which have different purposes.

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 provides explicit guidance on when to use this tool: '更新前に`get_form_fields` や`get_form_layout` でフィールド構造とレイアウトを確認し、利用するフィールドコードが最新であることをチェックしてから操作してください' (check field structure and layout before updating). It also distinguishes between two usage patterns (record_id vs updateKey) and specifies prerequisites for using updateKey (must be a duplicate-prohibited field).

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