Add Work Note or Comment to Record

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

Annotations indicate a non-read-only, non-idempotent write operation, and the description confirms this by describing adding notes/comments. It adds behavioral context by explaining the visibility difference (internal vs customer-visible) and the return value ('Confirmation with updated record'). This goes beyond the annotations but does not disclose additional side effects or authentication requirements, which are not expected given 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?

The description is well-structured: a concise purpose statement, an 'Args' section, a return note, and two illustrative examples. Every element adds value, and the information is front-loaded. The examples are not redundant but demonstrate typical usage patterns, making the tool easy to understand quickly.

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?

Given that there is no output schema, the description provides a sufficient overview of the tool's behavior, parameters, and return value. It could be more complete by mentioning potential errors or prerequisites (e.g., table must exist and support journal fields), but the information provided is adequate for an agent to correctly invoke the tool in common scenarios. The examples cover both primary use cases (work note and comment).

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 is empty, but the description provides detailed parameter semantics for table, identifier, work_note, and comment, including types, constraints, and examples. It clearly explains the difference between work_note and comment and states the requirement that at least one must be provided. This fully compensates for the schema's lack of parameters.

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 verb 'Add' and the resource 'work note or comment to any ServiceNow record that supports journal fields'. It distinguishes between internal work notes and customer-visible comments, which differentiates it from sibling tools like update_record or create_record. The examples further reinforce the specific use case.

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 clear context for when to use the tool (adding journal entries to ServiceNow records) and gives practical examples. It does not explicitly mention alternatives or exclusions, but the specification that it applies to records with journal fields and the nature of the operation implicitly distinguishes it from update/delete tools. The constraint that at least one of work_note or comment must be provided is also helpful usage guidance.

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