Push actions into a session's message queue (set fields, submit computation, trigger plot, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| actions | Yes | Array of SessionAction objects to push to the browser | |
| session_id | Yes | Session UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It introduces the 'message queue' concept but does not explain whether pushes are asynchronous, whether actions execute in order, or what happens on failure. The return value and error semantics are also omitted.
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?
A single sentence that is front-loaded and precise. It avoids redundancy and gives enough context without over-explaining.
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?
The schema is rich and detailed, making the tool usable for constructing actions. However, the description lacks operational guidance about queue behavior, ordering, or error handling, which is important for a tool with such a wide variety of action types and no output schema.
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 already provides 100% coverage with detailed descriptions for both top-level parameters and every nested action property. The description adds only a few action-type examples, which is marginal value beyond the schema.
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 uses a specific verb ('Push') and resource ('session's message queue') and lists concrete examples ('set fields, submit computation, trigger plot'). This clearly differentiates it from siblings like 'calculate' or 'get_session_state'.
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 guidance is provided on when to use this tool versus alternatives. It does not mention that this is for batching multiple actions or when a direct calculation would be preferred. No exclusions or prerequisites are stated.
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.
calculate_cas and calculate_cas_headless are explicitly aliases, creating two tools for the same purpose. Also, calculate and generate_prefilled_url both produce prefilled URLs, so their boundaries are not fully distinct.
Most tools follow a verb_noun pattern (calculate, create_session, get_session_state, list_calculators). The main deviation is calculate_cas_headless, which still fits the pattern but is an awkward alias name.
The 10-tool count is reasonable for a calculator service with session management. However, the alias tool is redundant and could be removed without losing functionality.
The tool set covers listing calculators, getting schemas, running calculations (standard and CAS), managing sessions, and generating URLs. Minor gaps like a dedicated way to delete sessions are addressed by close_session, so coverage is adequate.