Get state history for a session over time.
Returns timestamped datapoints with stress_score, state, and heart_rate for each observation.
Includes an overall trend: rising | falling | stable.
Use minutes parameter to control the lookback window (default: 5, max: 60).
Useful for detecting stress patterns during a conversation. Not a medical device.
| Name | Required | Description | Default |
|---|---|---|---|
| minutes | No | ||
| session_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden and does well: it discloses return fields (stress_score, state, heart_rate), the trend format (rising | falling | stable), the minutes parameter's range, and a disclaimer. It doesn't mention side effects or permissions, but as a 'get' operation this is minor. Adds value beyond the schema's scope.
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 efficiently packed: purpose, return data, trend, parameter control, use case, and disclaimer—all in a few sentences. No fluff, and key information is front-loaded.
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?
Even without annotations or an output schema, the description provides a comprehensive picture: what it does, what it returns (including field names and trend values), how to control the lookback window, and its intended use case. It's complete for a relatively simple read tool.
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 description explains the minutes parameter with its default (5) and adds a max (60) not present in the schema, which is helpful. However, session_id is only implied ('for a session') and not explicitly defined, though it's a required identifier. With 0% schema description coverage, the description partially compensates but could be more explicit.
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 a specific verb and resource: 'Get state history for a session over time.' It distinguishes from siblings like get_human_state (likely current state) and get_trigger_memory by focusing on historical timestamped data with a trend.
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?
It provides a clear use case: 'Useful for detecting stress patterns during a conversation.' It doesn't explicitly name alternatives, but the 'over time' and 'trend' language strongly implies a historical analysis tool compared to likely current-state siblings. A brief statement about when not to use it would push this to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a clearly distinct purpose: API key request/status, data ingestion, current state retrieval, session history, and trigger memory. No two tools overlap in functionality or could be confused.
All tool names follow a consistent snake_case verb_noun pattern (e.g., request_api_key, get_human_state, get_session_history). This creates a predictable and intuitive naming convention across the entire set.
Six tools is well-scoped for a real-time human state awareness API, covering the essential lifecycle (key management, data intake, state access, history, and psychological insights) without redundancy or bloat.
The tool surface fully covers the core domain: authentication (request and check key), data ingestion, current state, historical trends, and cross-session trigger profiles. There are no obvious missing operations for the stated purpose.