Skip to main content
Glama
Sign In

AimYear

by io.github.Yahhi
OverviewDiscussionsAdmin

Start session

start_session

Start a session of work and, if none is running, the timer. Returns a verdict: ok | stop | plan_first. On "stop" NO session is created: relay the message, ask the user; if they insist, call again with override=true. Several sessions may run at once (two terminals) and share attention by weight. Apps replaying a queued start pass op_id, their own session_id and start_at; an agent leaves all three out.

Input Schema

NameRequiredDescriptionDefault
areaNodefault work
taskYeswhat you are about to do, specific
op_idNofor apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out
itemIdNoplan item id
stepIdNopath step id
weightNoattention weight vs other sessions at the same time, default 1
leverIdNo
minutesNolength for a down timer, or the stand-up interval for an up timer
overrideNotrue only after the user confirmed past a stop
start_atNowhen the work began as ISO 8601 with offset, e.g. 2026-10-20T14:05:00+02:00. For apps delivering a request queued offline; an agent calling interactively leaves it out. Rejected before the session start; a clock more than 2 minutes ahead of the server is taken as now
directionNoup (default) counts elapsed time and runs until stopped, with a stand-up reminder every workMin; down is a fixed timebox, for a break
exclusiveNotrue: nothing else was happening then
projectIdNo
workplaceNo
session_idNofor apps: the session id the app minted itself. Create-if-absent: if a session with this id exists it is returned and nothing is created. An agent leaves it out; the server mints the id

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / op_id
      Added value: +{
+  "description": "for apps replaying queued requests: an id the app minted before its first attempt and reuses on retries, so the write is applied once and a retry gets the first answer back. Do not invent one; an agent calling interactively leaves it out",
+  "maxLength": 128,
+  "minLength": 8,
+  "type": "string"
+}
    • addedInput schema / properties / session_id
      Added value: +{
+  "description": "for apps: the session id the app minted itself. Create-if-absent: if a session with this id exists it is returned and nothing is created. An agent leaves it out; the server mints the id",
+  "maxLength": 64,
+  "minLength": 6,
+  "type": "string"
+}
    • addedInput schema / properties / start_at
      Added value: +{
+  "description": "when the work began as ISO 8601 with offset, e.g. 2026-10-20T14:05:00+02:00. For apps delivering a request queued offline; an agent calling interactively leaves it out. Rejected before the session start; a clock more than 2 minutes ahead of the server is taken as now",
+  "type": "string"
+}
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only cover the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds substantial behavior beyond that: the refusal path on 'stop', the fact that no session is created in that case, concurrent multi-session weighting, and the start_at clock-skew rule (>2 minutes ahead treated as now).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and the verdict alphabet, then the failure protocol, then the concurrency rule, then the app/agent parameter triage. Dense and mostly waste-free, though the final sentence compresses several distinct concerns into one clause chain.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter tool with no output schema, the description does the work the missing output schema would: it documents the returned verdict and the agent's obligations for each. The unusual parameters and the concurrent-session model are also covered, leaving only self-evident ids to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 80% schema description coverage the baseline is 3, but the description adds real meaning by triaging three otherwise-confusing params: apps replaying a queued start pass op_id, session_id and start_at, while an interactive agent leaves all three out. It adds nothing for itemId/stepId/leverId/projectId/workplace, but those are covered by the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Start a session of work') plus the secondary effect ('if none is running, the timer') and names the concrete return values (ok | stop | plan_first). An agent can distinguish this from add_session/edit_session/stop_session without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit branch handling: on 'stop' no session is created, relay the message, ask the user, and only re-call with override=true if the user insists. It also states the agent-vs-app calling rules. It does not, however, say when to prefer this over sibling tools like add_session or edit_session.

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

All AimYear toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources