一个用于记录估算和实际耗时的个人 MCP 服务器与命令行工具，让估算最终能够对照实际结果来检验，而不是凭感觉。
这是一个用于估算校准的数据收集工具，而不是估算器。 它永远不会替你估算任何东西。它记录的是你对一项工作估算的规模、计划最终变成的样子，以及这项工作实际消耗的墙钟时间。你拿这份记录做什么——比较、发现偏差、判断自己对某类工作一贯过于乐观——取决于你自己，也取决于之后读取存储的任何东西。这个工具的职责止于如实记录。
有四类东西会被记录：
Effort（工作项） — 一件值得单独跟踪的工作：一个 pull request、一个 mega-PR，任何有计划和大小的东西。一个 effort 从它拥有计划产物（一份 spec、一个 .PR.md，无论计划存在于什么之中）和初始估算的那一刻起就存在。在那之前，还没有什么可记录的。
Slice（切片） — effort 的一部分，通常是子 PR。切片可以被添加、针对某个 pull request 关闭、丢弃或重命名。在 effort 开始之前添加的切片属于原始计划的一部分；之后添加的则属于范围增长，两者在记录中保持可区分。
Interval（时间区间） — 一段打卡记录的时间跨度，通常对应某个切片。区间可以手动关闭，可以在会话结束时时钟仍在运行的情况下自动关闭，也可以在完全没有打卡记录时事后根据提交时间戳推导得出。
Absence（缺勤） — 完全没有工作的时间：假期、约会、无关的会议。缺勤是事后记录的，而且理应如此。它们会从所重叠的任何区间中扣除。
Related MCP server: Tempo MCP Server
每个估算都是一个 PERT 三元组 —— 乐观值、最可能值、悲观值 —— 以抽象的点数标度给出，绝不以小时为单位。期望值和标准差在读取时从三元组推导得出；任何地方都不会存储单一的"估算值是 N"这样的数字，因为一个光秃秃的数字会丢掉那些让它成为估算而非事实的不确定性。
点数的锚定方式是将手头的工作与形状相似的先前 effort 进行比较，而不是在脑子里把感觉到的工时数换算成点数。抽象标度的全部意义就在于，在你还不知道实际耗时的 effort 之间进行同类比较。
一个 effort 会被估算 两次：
初始估算，针对最初写下的计划进行，切片数量与计划开始时相同。
最终估算，在回顾时针对计划实际变成的样子进行——包括过程中插入的每一个切片。这是一个反事实问题："鉴于你现在对这件事实际发展走向的全部了解，你当初会估算多少？"——绝不是"花了多长时间？"，也绝不是对任何东西的测量。
把估算拆成两次，正是为了让估算可能出错的两种方式在事后可以分离。初始那次可能因为清单误差而出错——存在当时还没人知道的工作，或者原本以为存在的工作结果并不存在。最终那次针对计划实际变成的样子进行，隔离出规模误差——那些从头到尾都知道、只是判断错了的项目。每个 effort 一个数字会把两者混为一谈；两个数字、每次一个，就能把它们分开。
修订后的估算也可以在 effort 进行中记录——通常是在插入了原始计划中没有的切片时——不必等到回顾时。
默认假设一个正常的工作日，只记录与之不同的偏差。 打卡上下班是例外，不是常规——这个工具并不指望每天有八小时的秒表在跑。具体来说：
手动打卡的时间全额计入，无论落在什么钟点。晚上和周末也包括在内：如果你在周六 22:00 打卡，那就是真实时间，按原样记录，不应用任何工作时段调整。
工作时段模型只在实际没有记录任何时间的地方生效。 它恰好用在两个地方：
截断被遗忘的计时器。 如果会话结束时时钟仍在运行，区间会在配置的工作日结束时间关闭（或者，在配置的工作日和时段之外，上限为固定的会话时长），而不是无限期保持开启或被精确到分钟地猜测。
从提交时间戳重建区间，当某个切片从未有过任何打卡记录时。一组邻近的提交会变成一个推导出的工作会话，使用工作时段模型来判断它们之间的跨度中有多少算作工作，而不是隔夜间隙。
记录在某段时间上的缺勤会从它所重叠的任何区间——无论是打卡的还是推导的——中扣除，对于手动打卡的区间全额扣除，对于推导的区间则通过工作时段模型扣除。
MCP 服务器暴露的每个工具都恰好属于一个类别：
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，在做出估算时显示先前的 effort 以供比较。
status（状态） — current，报告当前打卡了什么以及从何时开始。
calibration（校准） — effort_table、effort_detail、summary，把累积的记录读出来。
记录、估算和状态工具绝不返回时长或聚合值。只有校准工具可以。 这一点在结构上得到强制：记录、估算或状态工具使用的每个响应模型都会被检查字段名是否包含 hours、minutes、duration、wall、average 或 share 等词，如果发现一个，检查就会失败。
原因不是整洁。在看到工作的真实时长之后做出的估算，是那个时长的锚定回声，而不是独立的判断——你产出的数字已经被刚刚看到的答案污染了。污染规则确保在做出估算或运行时钟期间，墙钟时间数字永远不会出现在工具响应中，从而使初始与最终的比较保持诚实。校准工具是豁免的，因为它们的全部目的就是在估算完成之后报告这些数字。
全部都是可选的；每一个都有默认值。如果两者出现不一致，以 src/estimate_maestro/config.py 为准，而不是这份列表。
变量 | 默认值 | 含义 |
|
| 存储目录的路径。 |
|
| 工作日的开始时间（ISO 8601 时间）。 |
|
| 工作日的结束时间（ISO 8601 时间）。 |
|
| 每日午休的开始时间，从工作秒数中排除。 |
|
| 每日午休的结束时间。 |
|
| 以逗号分隔的、计为工作日的星期几（周一 |
|
| 给在工作时段窗口之外开始的截断会话的最大时长。 |
|
| 在推导会话中最早提交之前增加的时间，用于覆盖第一次提交之前完成的工作。 |
|
| 提交之间的工作时间间隔，超过该间隔即认为推导会话已结束、新会话已开始。 |
|
|
|
ESTIMATE_MAESTRO_DERIVE_LEAD_IN_MINUTES 不得超过 ESTIMATE_MAESTRO_DERIVE_SESSION_GAP_MINUTES；否则服务器拒绝启动。
estimate-maestro-cli 覆盖不需要对话的日常记录操作：clock-in、clock-out、current、record-absence、effort-table 和 summary。那些只有作为估算对话的一部分才有意义的操作——启动 effort、修订估算、记录最终计划、收集提交——刻意只作为 MCP 工具而非 CLI 命令：它们本应发生在展示可比先前 effort 的会话中，而不是作为脱离该上下文的裸命令输入。
代码 | 含义 |
| 成功。 |
| 发生了错误。 |
| 仅 |
以下操作都没有替你执行过——请复制下面的命令并自行运行。
注册 MCP 服务器：
claude mcp add --scope user maestro-estimate -- uv --directory ~/mcp/estimate-maestro run estimate-maestro将两个技能符号链接到你的个人技能目录：
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-work将存储设为 git 仓库。其文件是纯文本且仅追加，因此可以提交并在机器之间漫游，而且它是所记录内容的唯一存续副本：其中丢失或错误的数据无法从任何其他地方重建。请保持其私有——它包含项目名称、分支名称以及耗时信息，这些都不应出现在公共仓库中。
mkdir -p ~/.local/share/estimate-maestro
git -C ~/.local/share/estimate-maestro init默认存储位置遵循 XDG Base Directory Specification，无需配置。仅当您希望将存储放在其他位置时才设置 ESTIMATE_MAESTRO_STORE——例如与其他个人仓库放在一起，这样更容易记得提交和推送。它必须对服务器和您的 shell 都可见，因此请将其放在两者都能读取的位置（通常是您的 shell 配置文件）：
export ESTIMATE_MAESTRO_STORE=~/somewhere/else将两个钩子脚本接入 ~/.claude/settings.json：将 hooks/session-end.sh 作为 SessionEnd 钩子（关闭被遗忘的计时器，并限制在配置的工作日内）以及将 hooks/session-start.sh 作为 SessionStart 钩子（报告计时器是否已在运行）：
{
"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" }
]
}
]
}
}如果 ~/.claude/settings.json 中已有 hooks 块，请将其合并到现有块中，而不是覆盖它。
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
