cos_observation_record

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

With annotations already providing readOnlyHint=false and destructiveHint=false, the description adds no operational context such as file modification, idempotency implications, or failure modes. The sentence contains no information about side effects or prerequisites beyond the act of recording.

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 only one sentence long, so it is concise, but it is under-specified rather than efficiently informative. 'Explicitly' adds little semantic value and the sentence does not earn its place by conveying necessary context.

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 two parameters and an output schema, this description is wholly inadequate. It does not explain what observation data is captured, how the file_path is used, or what the outcome of recording is. Despite output schema existing, the description still fails to provide a minimal mental model.

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 0% and the description does not mention file_path or tool_name. An agent cannot infer the meaning of these parameters or the role of tool_name's default 'Edit' from the text. The description fails to compensate for the absent schema descriptions.

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 'Record an observation explicitly' essentially restates the tool name and provides no detail about what constitutes an observation or how it differs from sibling recording tools like cos_metric_record or cos_work_log_append. The adverb 'explicitly' hints at manual capture but does not clarify scope or target.

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?

No usage conditions, prerequisites, or alternatives are mentioned. The description gives no indication of when to choose this over other record/log tools. It is tautological guidance: record an observation when you want to record an observation.

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