Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@estimate-maestro Log an initial PERT estimate for the current effort."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A personal MCP server and command-line tool for recording estimates and wall time, so that estimates can eventually be checked against outcomes instead of against feeling.
This is a data collection tool for estimation calibration, not an estimator. It never estimates anything for you. It records what you estimated a piece of work at, what the plan turned out to be, and how much wall time the work actually took. What you do with that record — comparing, noticing drift, deciding you were consistently optimistic about a certain kind of work — is up to you and to whatever reads the store later. The tool's job stops at recording honestly.
Four kinds of thing get recorded:
Effort — a piece of work worth tracking on its own: a pull request, a
mega-PR, anything with a plan and a size. An effort exists from the moment
it has a plan artefact (a spec, a .PR.md, whatever the plan lives in) and
an initial estimate. Before that point there is nothing to record yet.
Slice — a piece of an effort, usually a sub-PR. Slices are added, closed against a pull request, dropped, or renamed. A slice added before the effort starts is part of the original plan; one added afterwards is scope growth, and the two are kept distinguishable in the record.
Interval — a clocked-in span of time, ordinarily against a slice. Intervals are closed manually, closed automatically when a session ends with the clock still running, or derived after the fact from commit timestamps when nothing was clocked in at all.
Absence — time that was not worked at all: a holiday, an appointment, an unrelated meeting. Absences are recorded retroactively and are expected to be. They subtract from whatever interval they overlap.
Related MCP server: Tempo MCP Server
Every estimate is a PERT triple — optimistic, likely, pessimistic — given in an abstract points scale, never in hours. The expected value and the standard deviation are derived from the triple on read; nothing stores a single "the estimate is N" number, because a bare number throws away the uncertainty that made it an estimate rather than a fact.
Points are anchored by comparing the work at hand to prior efforts of similar shape, not by converting a felt number of hours into points in your head. The whole point of an abstract scale is to compare like with like across efforts whose actual duration you don't yet know.
An effort is estimated twice:
The initial estimate, made against the plan as first written, at the same slice count the plan started with.
The final estimate, made at the retrospective against the plan as it actually turned out — including every slice inserted along the way. This is a counterfactual: "given everything you now know about how this actually shook out, what would you have estimated?" — never "how long did it take?", and never a measurement of anything.
Splitting the estimate into two passes is what makes the two ways an estimate can go wrong separable after the fact. The initial pass can be wrong because of inventory error — work existed that nobody knew about yet, or work that was assumed to exist turned out not to. The final pass, made against the plan as it actually turned out, isolates sizing error — the items that were known about all along and simply judged wrongly. A single number per effort conflates the two; two numbers, one per pass, keep them apart.
A revised estimate can also be recorded mid-effort — typically when a slice is inserted that was not in the original plan — without waiting for the retrospective.
A normal working day is assumed by default, and only deviations from it are recorded. Clocking in and out is the exception, not the routine — the tool does not expect a stopwatch running for eight hours every day. Concretely:
Manually clocked time counts in full, whatever hours it falls in. Evenings and weekends included: if you clocked in at 22:00 on a Saturday, that is real time and it is recorded as such, with no working-hours adjustment applied to it.
The working-hours model only ever applies where no time was actually recorded. There are exactly two places it is used:
Clamping a forgotten timer. If a session ends with the clock still running, the interval is closed at the configured end of the working day (or, outside the configured working days and hours, capped at a fixed session length) rather than staying open indefinitely or being guessed at to the minute.
Reconstructing intervals from commit timestamps when nothing was ever clocked in for a slice. A cluster of nearby commits becomes a derived working session, using the working-hours model to decide how much of the span between them counts as work rather than an overnight gap.
An absence recorded over a span subtracts from any interval — clocked or derived — that it overlaps, in full for a manually clocked interval and through the working-hours model for a derived one.
Every tool the MCP server exposes falls into exactly one category:
recording — start_effort, add_slice, close_slice, drop_slice,
rename_slice, clock_in, clock_out, annotate_interval,
repair_interval, record_absence, record_revision,
record_final_plan, harvest_commits, record_landed_commit,
remap_commits, finish_effort.
estimation — reference_efforts, which shows prior efforts for
comparison while an estimate is being made.
status — current, which reports what is clocked in and since when.
calibration — effort_table, effort_detail, summary, which read
the accumulated record back out.
Recording, estimation and status tools never return a duration or an
aggregate. Only calibration tools may. This is enforced structurally: every
response model used by a recording, estimation or status tool is checked for
field names containing words like hours, minutes, duration, wall,
average, or share, and the check fails if one is found.
The reason is not tidiness. An estimate made after seeing the real duration of the work is an anchored echo of that duration, not an independent judgement — the number you'd produce is contaminated by having just seen the answer. The taint rule keeps a wall-time figure from ever surfacing in a tool response while an estimate is being made or a clock is being run, so that the initial-versus-final comparison stays honest. Calibration tools are exempt because their entire purpose is to report exactly those figures, once the estimating is done.
All are optional; every one has a default. Read from
src/estimate_maestro/config.py, not from this list, if the two ever
disagree.
Variable | Default | Meaning |
|
| Path to the store directory. |
|
| Start of the working day (ISO 8601 time). |
|
| End of the working day (ISO 8601 time). |
|
| Start of the daily lunch break, excluded from working seconds. |
|
| End of the daily lunch break. |
|
| Comma-separated weekdays counted as working days (Monday |
|
| Maximum length given to a clamped session that starts outside the working-hours window. |
|
| Time added before the earliest commit in a derived session, to cover work done before the first commit. |
|
| Working-time gap between commits beyond which a derived session is considered to have ended and a new one begun. |
|
| Minimum number of recorded efforts before |
ESTIMATE_MAESTRO_DERIVE_LEAD_IN_MINUTES must not exceed
ESTIMATE_MAESTRO_DERIVE_SESSION_GAP_MINUTES; the server refuses to start
otherwise.
estimate-maestro-cli covers the everyday recording actions that do not need
a conversation: clock-in, clock-out, current, record-absence,
effort-table, and summary. Actions that only make sense as part of an
estimating conversation — starting an effort, revising an estimate, recording
the final plan, harvesting commits — are MCP tools only, not CLI commands, on
purpose: they are meant to happen inside a session that shows comparable prior
efforts, not as a bare command typed without that context.
Code | Meaning |
| Success. |
| An error occurred. |
|
|
None of the following has been run for you — copy the commands below and run them yourself.
Register the MCP server:
claude mcp add --scope user maestro-estimate -- uv --directory ~/mcp/estimate-maestro run estimate-maestroSymlink the two skills into your personal skills directory:
ln -s ~/mcp/estimate-maestro/skills/recording-work-time ~/.claude/skills/recording-work-time
ln -s ~/mcp/estimate-maestro/skills/estimating-work ~/.claude/skills/estimating-workMake the store a git repository. Its files are plain text and append-only so that it can be committed and roam between machines, and it is the only surviving copy of what it records: a number lost or wrong in there cannot be reconstructed from anywhere else. Keep it private — it holds project names, branch names and how long things took, none of which belong in a public repo.
mkdir -p ~/.local/share/estimate-maestro
git -C ~/.local/share/estimate-maestro initThe default store location follows the XDG Base Directory Specification and
needs no configuration. Set ESTIMATE_MAESTRO_STORE only if you want the store
somewhere else — for instance alongside your other personal repositories, so it
is easier to remember to commit and push. It must be visible to both the server
and your shell, so put it wherever they both read (typically your shell
profile):
export ESTIMATE_MAESTRO_STORE=~/somewhere/elseWire the two hook scripts into ~/.claude/settings.json: hooks/session-end.sh
as a SessionEnd hook (closes a forgotten timer, clamped to the configured
working day) and hooks/session-start.sh as a SessionStart hook (reports
whether a timer is already running):
{
"hooks": {
"SessionStart": [
{
"hooks": [
{ "type": "command", "command": "~/mcp/estimate-maestro/hooks/session-start.sh" }
]
}
],
"SessionEnd": [
{
"hooks": [
{ "type": "command", "command": "~/mcp/estimate-maestro/hooks/session-end.sh" }
]
}
]
}
}Merge that into the existing hooks block in ~/.claude/settings.json rather
than overwriting it, if one is already there.
uv sync --locked
uv run ruff format --check
uv run ruff check
uv run pyright
uv run pytest src/ -vAdd a slice. One added while the effort is active is scope growth.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| effort | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only reveals that adding while the effort is active is scope growth, but says nothing about side effects, reversibility, permission requirements, or what happens to existing slices. For a mutating operation, this is insufficient transparency.
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, with two short sentences that both contribute information. The first defines the action; the second adds a relevant caveat. However, it is too sparse, and the structure lacks any emphasis on the parameters or usage context. Still, it is efficient and not padded with filler.
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's complexity is low (2 parameters) and an output schema exists, the description need not detail returns, but it still must explain parameter semantics and usage context. It does neither, and it omits key behavioral details beyond the single scope-growth note. The description is inadequate for an agent to confidently invoke the tool without additional guessing.
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 explain either parameter ('title' or 'effort'). The agent must rely solely on the schema's field names, which are generic and could refer to IDs, names, or other identifiers. The description adds no meaning to the parameters, failing to compensate for the lack of schema documentation.
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 states a specific verb ('Add') and resource ('a slice'), which clearly distinguishes it from sibling tools like close_slice, drop_slice, and rename_slice. The added note about scope growth when the effort is active provides meaningful context about the action's implication, going beyond a bare restatement.
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. The description does not mention any preconditions, alternatives, or situations where this tool is preferred. The scope-growth note is a behavioral warning, not a usage guideline, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach meeting participants or a note to an interval after the fact.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| effort | Yes | ||
| external | No | ||
| internal | No | ||
| interval | Yes | ||
| participants | No |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states that the tool attaches participants or a note after the fact, but it does not mention side effects, permission requirements, whether the operation is reversible, or how it interacts with existing data. For a mutation tool, this is insufficient.
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 a single, well-structured sentence that conveys the core action efficiently. It is not bloated, but it sacrifices necessary detail for brevity. The structure is front-loaded with the verb and resource, which is appropriate for quick scanning.
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 six parameters, two required, and no annotations, the description is incomplete. It does not explain the required parameters or the roles of external and internal, and it assumes the agent understands what an 'interval' is in this context. The presence of an output schema helps, but the description alone leaves too much to inference.
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. It mentions 'meeting participants' and 'note', which map to the participants and note parameters, but it provides no meaning for the required parameters 'effort' and 'interval', nor for 'external' and 'internal'. Agents are left guessing about the purpose of half the parameters.
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 states a specific verb ('attach') and resource ('interval'), and clarifies it is a post-hoc action ('after the fact'). It also names two of the key entities (participants, note). However, it does not differentiate from sibling tools like repair_interval or start_effort, so an agent might not know which to pick without further exploration.
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 given on when to use this tool versus alternatives. There is no mention of prerequisites, disambiguation from siblings, or conditions that make this tool the right choice. The agent must infer usage entirely from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an interval. Refused if one is already open.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | work | |
| note | No | ||
| effort | Yes | ||
| external | No | ||
| internal | No | ||
| work_slice | No | ||
| participants | No |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral disclosure. It reveals one behavior: refusal when an interval is open. However, it provides no details on side effects, success behavior, idempotency, permissions, or what happens to the provided parameters. For a write operation, this is insufficient transparency.
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 brief (two sentences) and front-loads the main action. It is not verbose, but it sacrifices utility for brevity. The refusal condition adds value, but the lack of any parameter or usage context makes it under-specified rather than concise in a helpful way.
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 7 parameters, no annotations, and no parameter descriptions, the description is far from complete. An agent cannot confidently invoke this tool without additional knowledge about the arguments. The output schema exists but does not compensate for the missing parameter semantics and behavioral context.
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 has 7 parameters with 0% description coverage. The description adds no meaning to any parameter (effort, kind, note, external, internal, work_slice, participants). An agent cannot infer which fields are required, what 'effort' expects, or how 'external' vs 'internal' influence the interval. The description completely fails to compensate for the schema's lack of explanations.
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 states a specific action ('Start an interval') and a key constraint ('Refused if one is already open'). It clearly indicates what the tool does, though it doesn't explicitly differentiate from sibling tools like start_effort or clock_out. The resource (interval) and verb are precise enough for basic selection.
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 gives no guidance on when to use this tool versus alternatives. It only implies that it should not be used when an interval is already open. No mention of scenarios where start_effort or other siblings would be more appropriate. An agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the open interval.
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | ||
| note | No |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the action without explaining consequences, side effects, prerequisites, or failure behavior (e.g., what happens if no interval is open). This is severely inadequate.
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 a single, concise sentence with no wasted words, placing the key action at the start. It achieves maximum conciseness, though this is at the expense of substance.
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 description is insufficient for a tool in a domain with numerous sibling tools (clock_in, start_effort, etc.). It does not explain what an open interval is, when to call this tool, or what the output signifies. Given the optional parameters and presence of an output schema, much needed context is missing.
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 does not mention either parameter ('at' or 'note') and adds no meaning beyond the schema's type definitions. With 0% schema description coverage, the description fails to compensate for the missing parameter explanations, leaving the agent without hints about timestamps or note content.
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 'Close' and object 'the open interval', clearly indicating the action of ending an interval. However, it does not define what an interval is or differentiate it from sibling tools like clock_in or start_effort, leaving some ambiguity for an agent without domain context.
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 provides no guidance on when to use this tool, such as whether an interval must be open first, nor does it mention any alternative tools or conditions for exclusion. It is a bare statement with no decision aid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close a slice against its pull request.
| Name | Required | Description | Default |
|---|---|---|---|
| effort | Yes | ||
| work_slice | Yes | ||
| pull_request | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'close' without disclosing side effects, whether it is destructive, requires specific permissions, or is reversible. The agent gets no insight into consequences beyond the bare action.
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 a single concise sentence, which is appropriately minimal and avoids verbosity. However, it is so brief that it lacks structure or distinction; it is efficient but not informative, earning a mid-to-high score for conciseness alone.
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 three-parameter tool with no annotations and no parameter descriptions, the description is severely incomplete. It does not explain the domain concepts (slice, effort, pull request), the expected workflow, or the output. An agent would have no idea how to correctly invoke this 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 schema has 0% description coverage and the parameters (effort, work_slice, pull_request) are completely undocumented. The description mentions none of them, so the agent has no idea what values to provide or what 'effort' or 'work_slice' refer to in this context.
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 states a clear verb ('close') and resource ('slice') with a context ('against its pull request'), and it is distinct from sibling tools like add_slice or drop_slice. However, it could be more explicit about what closing entails, but it is not a tautology and is sufficiently clear.
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?
There is no guidance on when to use this tool versus alternatives, nor any context about prerequisites or conditions. The description simply states the action without indicating the appropriate workflow stage or how it differs from similar operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is clocked in, and since when.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| since | No | |
| effort | No | |
| interval | No | |
| work_slice | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the output ('what is clocked in, and since when') but does not disclose any behavioral traits such as whether it is read-only, whether it might return null if nothing is clocked in, or any limitations. For a simple query, this is minimal but not misleading.
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 a single, front-loaded sentence that clearly communicates the tool's function. It is appropriately sized for a zero-parameter read tool—no wasted words, no redundancy.
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 no parameters and an output schema that likely describes the return format, the description gives enough context: it tells the agent what information it will receive (current clocked-in item and its start time). It doesn't explain edge cases (e.g., nothing clocked in), but given the simplicity, it is reasonably complete.
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 schema has zero parameters, so the baseline is 4. The description adds no parameter meaning because there are none to explain. It correctly focuses on the output rather than inputs.
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 states the tool reports what is currently clocked in and the starting time. It is specific and distinguishes from action tools like clock_in/clock_out and summary tools like effort_table. The verb is implicit (reports/queries), but the resource is clear enough for an agent to understand its purpose.
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 gives no explicit guidance on when to use this tool versus alternatives. It doesn't mention that it's a read-only query, nor does it contrast with sibling tools that might provide similar information (e.g., effort_table or summary). The usage context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drop a slice that turned out to be unnecessary.
| Name | Required | Description | Default |
|---|---|---|---|
| effort | Yes | ||
| reason | Yes | ||
| work_slice | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a mutation (dropping a slice) but does not mention consequences, reversibility, required permissions, or side effects. The phrase 'that turned out to be unnecessary' adds a slight hint of intent but nothing about how the operation behaves (e.g., whether it permanently deletes or just marks as discarded).
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 a single sentence, so it is concise. However, it front-loads only a vague reason ('turned out to be unnecessary') and omits essential practical information. Conciseness is achieved at the expense of substantive content, making it under-specified rather than effectively structured.
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 tool has three required parameters and an output schema, yet the description provides no context on how parameters relate, what the expected output is, or any constraints. The description is inadequate for a tool that likely mutates state and requires specific inputs. An agent would struggle to invoke it correctly without further schema documentation.
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 undocumented parameters. It does not. The description offers no explanation of what 'effort', 'work_slice', or 'reason' refer to beyond their names, and does not clarify their formats or relationships. This is a critical gap for an agent to call the tool correctly.
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 the verb 'drop' and the resource 'slice', indicating the tool removes a slice. The phrase 'that turned out to be unnecessary' adds a hint of the rationale but does not differentiate it from sibling tools like close_slice or rename_slice. The purpose is clear at a basic level, but no explicit distinction is made.
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 such as close_slice or add_slice. The description gives no scenario-based advice, no conditions for selection, and no mention of exclusions. It only states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One effort's full event history.
| Name | Required | Description | Default |
|---|---|---|---|
| effort | Yes |
| Name | Required | Description |
|---|---|---|
| row | Yes | |
| meta | Yes | |
| slices | Yes | |
| commits | Yes | |
| estimates | Yes | |
| intervals | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'full event history' – it does not state that this is a read-only operation, imply any implications for large histories, or mention pagination or data format. The agent cannot predict performance or side effects from this text.
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?
While extremely brief, this is under-specification rather than concise efficiency. The single fragment 'One effort's full event history' repeats what the tool name already implies and adds no new information. It fails to earn its placement by contributing actionable detail.
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 existence of an output schema is not sufficient – the description should explain what the history includes (e.g., timestamps, states, actors) and any caveats. Given the tool's apparent complexity (multiple sibling operation types), a one-line description is inadequate for correct invocation and result interpretation.
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 schema provides zero description coverage (0%), so the description must explain the 'effort' parameter. It only says 'effort' with no additional typing like a contract ID, name, or unique key. The agent cannot tell what format or how to obtain a valid value from this description alone.
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 phrase 'full event history' clearly indicates a retrieval operation scoped to one effort. It distinguishes itself from sibling tools like 'summary' or 'current' by focusing on the complete event log. However, it does not explicitly name the resource as the subject of a verb (e.g., 'fetches'), so it stops short of a precise action-resource statement.
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 given for when to call this tool versus alternatives. It does not mention that it complements 'summary' or 'effort_table', nor does it advise against calling it when only a current snapshot is needed. The description leaves the agent to infer appropriate usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One near-raw row per effort: estimates, wall hours, slice counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'near-raw row,' which hints at unaggregated data, but it does not explicitly state that the operation is read-only, nor does it mention any side effects, prerequisites, or dependencies. This is insufficient for a tool with zero annotation coverage.
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 a single sentence, which is concise and front-loads the key idea about raw effort rows. However, it is also terse to the point of vagueness, lacking a verb and clear scope. The structure is clean, but the content is thin, so it earns a 4 for brevity but not for richness.
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 no parameters and an output schema exists, the description only needs to establish purpose and usage context. It provides a minimal idea that it returns raw effort rows with specific metrics, but it fails to explain how it relates to siblings or when it is preferable. The presence of an output schema covers return values, but the purpose remains ambiguous, making it minimally complete.
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 tool has zero parameters, so there is nothing to explain in the description. The description mentions the content of rows (estimates, wall hours, slice counts), which relates to output rather than parameters. With 0 parameters, the baseline of 4 applies because the description does not need to compensate for missing parameter information.
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 identifies the resource (effort) and hints at the output content (estimates, wall hours, slice counts), but it lacks an explicit verb like 'list' or 'get' and does not distinguish itself from siblings such as effort_detail or summary. The purpose is implied rather than directly stated, making it moderately clear but not precise.
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?
There is no guidance on when to use this tool versus the many siblings (effort_detail, summary, current, etc.). The description does not mention any conditions, filters, or alternative tools, leaving the agent without a basis to select this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an effort done.
| Name | Required | Description | Default |
|---|---|---|---|
| effort | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only implies a state mutation ('mark done') without detailing side effects, reversibility, required prior states, or any impact on related entities like intervals or slices. The description is insufficient for an agent to understand the full consequences of the call.
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 a single, brief sentence that is easy to parse and front-loaded with the core action. It is appropriately concise for a simple tool, though additional structured guidance would be beneficial.
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 low complexity (one parameter), the description is still incomplete. It fails to provide usage context (e.g., relationship to start_effort, lifecycle) and does not compensate for missing annotations. An output schema exists but the description does not mention return behavior, and there is no indication of when this is the appropriate 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?
Schema description coverage is 0%, so the description must clarify the 'effort' parameter. It does not explain whether this is an ID, name, or how to reference an effort. The tool name and description provide minimal inference, leaving the parameter semantics largely undocumented.
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 'Mark an effort done' states a clear verb and resource. It is distinct from sibling tools like 'start_effort' which imply the opposite action. The purpose is unambiguous and specific.
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. There is no mention of prerequisites, such as requiring an effort to be started first, or when not to use it. The description offers no context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy commit metadata from a working tree into the store.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| since | Yes | ||
| until | Yes | ||
| effort | Yes | ||
| work_slice | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It implies a write operation ('copy ... into the store') but doesn't detail side effects, whether it's destructive, requires specific permissions, or how the store is updated (overwrite vs append). The high-level phrase 'copy' is vague about the actual mechanism and consequences.
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 a single, concise sentence with no fluff. It is front-loaded with the core action and destination. However, it is so short that it borders on under-specification rather than efficiency, but for what it says, it is appropriately sized.
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 5 required parameters, no parameter documentation, and no usage guidance, the description is wholly incomplete. Even if an output schema exists, an agent cannot correctly invoke this tool without understanding the parameters and expected context. The description fails to provide the necessary context for safe and correct usage.
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 schema has 5 required parameters with 0% description coverage, and the description provides no explanation for any of them. An agent cannot infer what 'effort', 'work_slice', 'path', 'since', and 'until' represent from the description alone. This is a severe gap in usability.
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 states a specific action (copy), a resource (commit metadata), and a source/destination (working tree into store). This is clear enough to convey the core function, though it doesn't explicitly differentiate from sibling tools like 'record_landed_commit' or 'remap_commits'. The verb 'copy' is unambiguous about the operation.
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?
There is no guidance on when to use this tool versus alternatives. The description doesn't mention prerequisites, expected context, or any exclusions. For a tool that interacts with a working tree and store, an agent would benefit from knowing when to choose 'harvest_commits' over similar commit-related tools, but this is entirely absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declare time not spent working. Retroactive by design.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| note | No | ||
| stop | Yes | ||
| start | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the retroactive nature, which is useful, but it says nothing about side effects, permissions, potential conflicts with existing time records, or how the absence integrates with other data. This is minimal for a tool that records data.
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 (two short sentences) with no redundant wording, which is good for front-loading. However, it is under-specified for a tool with 4 parameters and 0% schema coverage; while concise, it sacrifices necessary detail. It is efficient but not fully effective.
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?
Although an output schema exists (so return values need not be described), the description is incomplete for correct usage. It lacks any parameter explanation, usage context, behavioral details, or prerequisites. For a tool with required start/stop/kind and optional note, this description leaves too much unspecified.
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% — the schema only provides property names and types, no descriptions. The tool description must therefore explain the parameters, but it does not. It gives no meaning for 'start', 'stop', 'kind', or 'note', leaving the agent to infer everything from the schema's titles and enum values, which is insufficient.
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 ('Declare') and a clear resource ('time not spent working'), which distinguishes the tool's general purpose from siblings like clock_in/clock_out. The phrase 'Retroactive by design' adds a distinct characteristic, but it does not explicitly contrast with any sibling tool. Overall, the purpose is clear and unambiguous.
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 does not state when to use this tool over alternatives. It only hints at retroactive recording, but there is no explicit guidance on scenarios (e.g., 'use for past absences, use clock_in/clock_out for real-time tracking'). With 19 sibling tools, providing usage context is essential; this description offers none.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the final plan and the counterfactual estimate against it.
| Name | Required | Description | Default |
|---|---|---|---|
| effort | Yes | ||
| likely | Yes | ||
| plan_path | Yes | ||
| rationale | Yes | ||
| optimistic | Yes | ||
| pessimistic | Yes | ||
| summary_text | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. The description merely says 'Record,' implying a write operation, but does not explain side effects (e.g., what is stored, if it overwrites, if it requires prior actions), authentication needs, or error conditions. This is severely lacking for a mutation tool.
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 a single sentence, so it is concise in word count, but it is under-specified rather than efficiently informative. It lacks structure (e.g., heading, bullet points, parameter explanations) and does not front-load actionable guidance. Conciseness without substance is insufficient.
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 7 required parameters, zero schema descriptions, no annotations, and a one-line description, the information is completely inadequate. An agent cannot infer parameter formats, required values, or relationships between parameters. The presence of an output schema does not help with input construction. This tool is far from complete for reliable invocation.
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% for 7 required parameters, and the description adds no parameter-specific meaning. It only vaguely hints at 'final plan' and 'counterfactual estimate' without mapping to effort, plan_path, summary_text, optimistic/likely/pessimistic, or rationale. The agent has no help understanding what these parameters mean or how to fill them.
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 states a specific action ('Record the final plan') and references a 'counterfactual estimate,' giving some clarity about the tool's purpose. However, it does not differentiate from sibling tools (e.g., record_revision, finish_effort) and uses jargon ('counterfactual estimate') without explanation, leaving ambiguity about the exact resource and action.
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 provides no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusion criteria, leaving the agent without actionable direction on tool selection among the 20 sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the durable commit that landed on the default branch.
| Name | Required | Description | Default |
|---|---|---|---|
| effort | Yes | ||
| identifier | Yes | ||
| repository | Yes | ||
| work_slice | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only implies a write operation ('record') but fails to mention side effects, required conditions, idempotency, error handling, or any other behavioral traits.
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 a single sentence, which is concise and front-loaded. However, it is under-specified to the point of being unhelpful, so the conciseness does not compensate for the lack of substance.
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 four required parameters, no annotations, and zero schema descriptions, the description is far from complete. While an output schema exists (so return values are covered), the description fails to address the core usage context, parameter meanings, and when to invoke the 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?
Schema description coverage is 0%, and the description doesn't explain any of the four required parameters (effort, work_slice, repository, identifier). The agent has no way to interpret what these parameters mean or what values to provide, making the tool essentially unusable without external knowledge.
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 states a specific verb (record) and resource (durable commit that landed on the default branch), giving a clear purpose. However, it doesn't explicitly differentiate from sibling tools like record_revision or harvest_commits, and the term 'durable' is ambiguous.
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 provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage without any help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a revised estimate, typically when a slice is inserted.
| Name | Required | Description | Default |
|---|---|---|---|
| effort | Yes | ||
| likely | Yes | ||
| rationale | Yes | ||
| optimistic | Yes | ||
| pessimistic | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the action ('record') but does not describe what happens to existing data, whether it modifies prior estimates, requires authentication, or has side effects. There is no mention of reversibility, idempotency, or concurrency, and the output schema is not referenced. For a write operation, this is a significant gap.
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 a single sentence, which is appropriately concise, but it front-loads purpose without providing necessary context for the tool's parameters or behavior. It earns its place as a purpose statement, but the brevity leaves out critical information, so it is not optimally structured for usability.
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?
With five required parameters, no annotations, and zero schema descriptions, the tool requires more contextual guidance. The description only covers the general purpose and a typical trigger, omitting parameter semantics, when not to use it, and behavioral expectations. An output schema exists but is not described, so the agent has no idea what the return value will be. This is incomplete for a tool of this complexity.
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 explain any of the five parameters (effort, optimistic, likely, pessimistic, rationale). The parameter names offer some hints, but without semantic context (e.g., units, ranges, relationships), an agent cannot reliably determine values. The description adds no parameter meaning and fails to compensate for the schema gap.
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 the tool records a revised estimate and gives a typical context ('when a slice is inserted'). This distinguishes it from siblings like 'record_final_plan' or 'repair_interval' at a high level, though it does not name alternatives explicitly. It is not a tautology and conveys the core purpose effectively.
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 provides a typical usage scenario ('when a slice is inserted') but does not explicitly say when to use this tool over alternatives, nor does it mention exclusions or prerequisites. An agent would have to infer that this is for revisions as opposed to initial estimates or final plans, but there is no direct guidance compared to sibling tools like 'record_final_plan'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prior efforts with their summaries and estimates, for comparison. No actuals.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral details. It discloses that actuals are not included, which is a key restriction, but it doesn't state whether the operation is read-only, whether it has pagination, or what the output structure looks like. The lack of annotation coverage makes this a significant gap.
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 short, which is good for conciseness, but it sacrifices necessary detail. It says nothing about parameters or usage context, making it under-specified rather than effectively concise. It does not front-load any actionable details beyond the core purpose.
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 two parameters, an output schema, and no annotations, the description is insufficient. It does not explain what the 'kind' filter does, what 'limit' controls, or what 'reference efforts' means in practice. The output schema exists, so return values are covered, but the tool's semantics and usage are not adequately described.
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 has zero description coverage, and the description does not mention the 'kind' or 'limit' parameters at all. It only elaborates on the general purpose, leaving the agent without any semantic guidance for how to populate the parameters. This is a critical omission given the 0% coverage.
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 states it provides prior efforts with summaries and estimates for comparison, and explicitly excludes actuals. This distinguishes it from tools that report actual data, but it doesn't specify the verb (e.g., 'list', 'retrieve') or fully clarify its scope relative to sibling tools like effort_table or effort_detail. It's clear enough but not highly specific.
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?
There is no guidance on when to use this tool versus siblings like effort_table or summary. The phrase 'for comparison' implies a use case, but it doesn't state when not to use it or what alternatives exist. This leaves the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map a rewritten commit id onto its replacement.
| Name | Required | Description | Default |
|---|---|---|---|
| new | Yes | ||
| old | Yes | ||
| effort | Yes | ||
| reason | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It merely says 'map' without indicating whether this performs a mutation, requires specific permissions, or is reversible. The impact on data (e.g., creating a mapping record) is not disclosed, leaving agents uncertain about side effects.
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 a single, tightly worded sentence with no superfluous content. It front-loads the core action and object, making it immediately scannable. Conciseness is optimal, though it sacrifices depth (captured in other dimensions).
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 requires four mandatory parameters and has an output schema, the description should provide more context about the operation's purpose, side effects, and parameter roles. It lacks any indication of what the output contains or how 'effort' and 'reason' relate to the mapping. The description is inadequate for a complete agent decision.
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 undocumented parameters. It clarifies 'old' and 'new' implicitly through the phrase 'commit id onto its replacement,' but 'effort' and 'reason' remain entirely unexplained. The description adds no value beyond the schema field names, failing to make the parameters self-explanatory.
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 states a clear action ('Map') and a specific resource ('a rewritten commit id onto its replacement'), which distinguishes it from siblings like record_revision or harvest_commits. However, it does not explicitly name a sibling or clarify the context of 'rewritten' beyond the phrase, so it stops short of a 5.
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. There is no mention of scenarios like post-rebase remapping, nor any exclusions or prerequisites. The agent is left to infer the usage context from the terse description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a slice.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| effort | Yes | ||
| work_slice | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It merely states the action without revealing side effects, required permissions, reversibility, or consequences for associated data. The presence of required parameters like 'effort' and 'work_slice' hints at deeper semantics that are left unexplained. This is inadequate for an operation that likely mutates state.
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?
While the three-word sentence is technically concise, it is underspecified to a fault. It lacks necessary context about the tool's operation, parameters, and usage. Conciseness should serve clarity, not sacrifice it. This is not efficient conciseness but minimalism without substance.
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 three required parameters, no schema descriptions, no annotations, and multiple sibling slice operations, the description is grossly incomplete. It does not explain what a 'slice' is, how 'effort' relates to 'work_slice', what the expected return value is, or any edge cases. The absence of any contextual guidance makes correct invocation nearly impossible for an agent.
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 adds no explanation for any of the three parameters (title, effort, work_slice). The schema only provides types and names, leaving agents to guess the meaning and relationship between them. The description fails to compensate for the missing schema documentation, making it impossible to know how to fill parameters correctly.
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 states a specific verb ('Rename') and resource ('a slice'), which clearly conveys the core action. It distinguishes this tool from sibling slice operations (add_slice, close_slice, drop_slice) because 'rename' is semantically distinct from add/close/drop. However, it lacks explicit differentiation context, so it doesn't reach a 5.
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?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, and no indication of expected effects or warnings. The description 'Rename a slice' provides zero usage context. This is a complete absence of usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Correct an interval's bounds. Appends; never rewrites.
| Name | Required | Description | Default |
|---|---|---|---|
| stop | No | ||
| start | No | ||
| effort | Yes | ||
| interval | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It discloses that the operation appends rather than rewrites, which is a key behavioral trait. However, it doesn't explain side effects, idempotency, or what happens to existing data beyond the append nature. Minimal but non-zero transparency.
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?
Very concise: two short sentences with no filler. The key behavioral trait is front-loaded. Could be slightly more explicit about parameters, but structure is efficient.
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 4 parameters, no annotations, and an output schema, the description is too sparse. It doesn't explain how to provide the required parameters or what the output represents. The agent would need to inspect the schema deeply and still lack context on usage semantics.
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 coverage is 0%, so the description must compensate. It mentions 'bounds' which maps to start/stop, but gives no explanation of the required 'effort' and 'interval' parameters. The agent cannot infer how to specify which interval to correct or what effort context is needed.
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 ('Correct') and resource ('an interval's bounds'), and adds a distinguishing behavioral trait ('Appends; never rewrites'). This clearly separates it from sibling tools that start, slice, or record actions, though it doesn't name alternatives explicitly.
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 explicit guidance on when to use this tool versus alternatives. It implies use when bounds need correcting, but doesn't state conditions, exclusions, or mention sibling tools. The agent is left to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an effort from a plan artefact and an initial PERT estimate.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| title | Yes | ||
| likely | Yes | ||
| plan_path | Yes | ||
| rationale | Yes | ||
| optimistic | Yes | ||
| pessimistic | Yes | ||
| work_slices | Yes | ||
| summary_text | Yes |
| Name | Required | Description |
|---|---|---|
| recorded | Yes | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'Create' which suggests mutation, but does not explain side effects, required permissions, reversibility, or what happens to existing efforts. The output schema is not referenced, leaving the agent without expectations of the result.
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?
One sentence, no wasted words, and the core purpose is front-loaded. However, it is so under-specified it borders on a fragment, lacking any structural benefit for a complex 9-parameter tool.
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 9 required parameters, no annotations, and an output schema, the description is woefully incomplete. It fails to explain any parameter semantics, preconditions, or return behavior, leaving most essential context missing.
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. It only vaguely mentions 'plan artefact' and 'PERT estimate' without mapping to any of the 9 parameters (title, kind, plan_path, summary_text, optimistic, likely, pessimistic, rationale, work_slices). No meaning is added beyond the bare 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?
States a specific verb ('Create') and resource ('effort'), and mentions two key inputs ('plan artefact' and 'initial PERT estimate'). This distinguishes it from siblings like finish_effort or add_slice, though it doesn't explicitly name alternatives.
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 on when to use this tool versus siblings. The description implies you need a plan artefact and a PERT estimate, but does not state prerequisites, preconditions, or appropriateness relative to other lifecycle tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate calibration, or an honest refusal when there is too little data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| note | Yes | |
| efforts_counted | Yes | |
| mean_hours_per_point | Yes | |
| mean_inventory_growth | Yes | |
| median_hours_per_point | Yes | |
| median_inventory_growth | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose one behavioral trait beyond the obvious: an 'honest refusal when there is too little data,' which signals the tool can return a refusal rather than a fabricated aggregate. But nothing else about behavior is stated — no mention of whether the aggregation is computed on-demand or cached, what states of calibration data trigger the refusal threshold, or what the refused/aggregate outputs look like.
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, front-loaded sentence with no filler words. It earns its place but trades away critical clarity for brevity — the 'calibration' term is never unpacked, and the refusal condition is compressed into a subordinate clause. Economical, but arguably under-specified in service of economy.
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?
Mitigating factors: an output schema exists (though not shown) explaining return values, and zero parameters simplify the call contract. Nevertheless, the description leaves the core noun undefined — what 'calibration' aggregates — and never outlines the threshold for 'too little data.' For a tool that is entirely about its output semantics, this is a meaningful gap.
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?
Zero parameters, so the baseline is 4 and there is nothing for the description to clarify. The one relevant semantic — the tool operates on existing calibration state rather than requiring arguments — is implicitly conveyed by the empty schema, and the refusal phrase adds the data-sufficiency condition.
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?
States a verb ('aggregate') and a resource ('calibration'), so it clears the tautology bar. However, 'calibration' is a domain-specific term never explained — in a family of time-tracking/effort tools (clock_in, record_revision, effort_table), it's unclear whether calibration means planned-vs-actual comparison, summary statistics, or something else. The agent can guess but can't be sure.
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 on when to call this versus any sibling. None of the 19 sibling tools are referenced, and no condition distinguishing 'aggregate calibration' from similar summarization operations is given. An agent facing siblings like effort_table and effort_detail has no basis for choosing summary over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0add_sliceannotate_intervalclock_inclock_outclose_slicecurrentdrop_sliceeffort_detaileffort_tablefinish_effortharvest_commitsrecord_absencerecord_final_planrecord_landed_commitrecord_revisionreference_effortsremap_commitsrename_slicerepair_intervalstart_effortsummaryEvery tool has a clearly distinct purpose. Even overlapping domains like commits (harvest, record, remap) and intervals (clock, annotate, repair) are separated by specific actions and targets. No two tools could be easily confused for the same operation.
The majority of tools follow a consistent verb_noun pattern (e.g., repair_interval, start_effort, add_slice). A few query tools are named as nouns (current, summary, effort_table, effort_detail), which is a minor deviation but still readable and sensible for retrieval operations.
With 21 tools, the surface is substantial but justified by the domain's complexity—covering efforts, intervals, slices, commits, estimates, and queries. Each tool adds distinct functionality, though the count is on the higher end and could feel heavy for simpler use cases.
The toolset provides comprehensive lifecycle coverage: starting and finishing efforts, managing slices (add/close/drop/rename), tracking time (clock in/out, absence), revising estimates, recording commits, and rich reporting (current, table, detail, summary). No obvious gaps or dead ends are apparent.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Privacy-first work tracking with summaries, reports, coaching, and AI-ready long-term memory.
Time tracking, live project budgets, and billing exports for service firms.
Timen time tracking — timers, time entries, reports, projects, and clients.
Read time entries, projects, clients, tasks and invoices; log and update tracked time.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Odalrick/estimate-maestro'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
