create_decision_input

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

Annotations declare readOnlyHint=false (write operation) and destructiveHint=false, so the write nature is already known. The description adds the WRITE_ENABLED requirement and the fact that it's an 'add' operation, which is useful. However, it does not disclose whether the operation appends or overwrites existing inputs, nor any response behavior. It does not contradict 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 a single, concise sentence that immediately states the action, the target resource, and a critical requirement. No unnecessary words or fluff. It is front-loaded with the core information, making it easy for an agent to parse 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 the tool is a simple CRUD operation with a fully described schema and the description names the target table, the essential information is present. The lack of an output schema is not critical for a create operation, and the agent can infer the purpose from the name and schema. However, it could mention that this is for adding an input to an existing decision table, which is implied but not explicit.

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 schema already documents all five parameters (name, type, order, fields, decision_sys_id). The description does not add any additional parameter meaning beyond what is already provided. It only mentions the target table, which is already captured in the decision_sys_id parameter. Thus, it adds no value beyond the baseline for fully covered schemas.

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 ('Add an input to a decision table') and specifies the exact table (sys_decision_input). It distinguishes itself from siblings like create_decision_table (which creates the table itself) and list_decision_inputs (which lists existing inputs). The verb-resource pairing is unambiguous.

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 includes the prerequisite 'Requires WRITE_ENABLED=true', which is a useful condition, but it does not explain when to use this tool versus alternatives such as create_decision_table or update operations. The usage context is implied (add input to an existing decision table) but not explicitly stated, and no alternatives are named.

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