cortex_record_event

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

The description discloses two important behavioral traits: 'hot-path' (performance-sensitive) and 'non-blocking' (asynchronous or fire-and-forget). These are valuable beyond what annotations provide (none exist). However, it doesn't disclose what happens on failure (e.g., is the event silently dropped?), whether events are persisted or volatile, or any ordering guarantees. For a logging tool, these behavioral details matter significantly for an agent deciding whether to rely on it.

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 extremely concise at 5 words, which is appropriate for a hot-path logging tool. It front-loads the most critical information (hot-path, non-blocking) and doesn't waste words. However, it's almost too terse – a bit more context about what 'episodic event' means in this system would be valuable without sacrificing conciseness.

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 has 6 parameters, 5 required, no schema descriptions, no annotations, and no output schema details, the description is insufficient. The agent needs to know what event types are valid, what outcome_status values are expected, and what the payload structure should be. The output schema exists but its contents aren't shown, so the description should compensate. The 'hot-path non-blocking' context helps but doesn't address the core question of how to properly construct an event record.

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%, so the description must compensate for the lack of parameter documentation. The description mentions 'episodic event logging' but doesn't explain what each parameter means (e.g., what constitutes an 'event_type', what 'outcome_status' values are expected, what 'payload' should contain). With 6 parameters and 5 required, the agent has no guidance on how to construct valid calls. The parameter names are somewhat self-explanatory, but the description adds no semantic value beyond the schema itself.

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 'Hot-path non-blocking episodic event logging' clearly identifies the tool as an event logging mechanism with specific performance characteristics (hot-path, non-blocking). It distinguishes itself from sibling tools like cortex_query_memory or cortex_inspect_graph, which are read-oriented, and cortex_force_consolidation, which is a maintenance operation. However, it doesn't explicitly state what 'record_event' does with the event data or how it relates to the episodic memory system, leaving some ambiguity about the exact resource being acted upon.

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 in hot-path scenarios where non-blocking behavior is required, which gives some context for when to use this tool. However, it doesn't explicitly state when NOT to use it or mention alternatives like cortex_update_scratchpad for state updates or cortex_query_memory for retrieval. The 'hot-path' qualifier suggests performance-critical contexts, but there's no explicit guidance on choosing between this and other logging/recording tools.

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