個人的なMCPサーバー兼コマンドラインツールで、見積もりと実経過時間を記録し、見積もりを最終的に「感覚」ではなく「結果」と照合できるようにするためのものです。
これは見積もりキャリブレーションのためのデータ収集ツールであり、見積もりツールではありません。 何かの見積もりを自動で行うことは一切ありません。記録するのは、ある作業に対してあなたが立てた見積もり、計画が実際にどうなったか、そしてその作業に実際にかかった実時間です。その記録をどう使うか（比較する、ずれに気づく、ある種の作業について一貫して楽観的だったと判断するなど）は、あなた自身と、後でストアを読み出すものに委ねられています。このツールの役割は、正直に記録するところまでで終わりです。
記録されるものは4種類あります。
Effort（エフォート） — 単独で追跡する価値のある作業のかたまり。プルリクエスト、メガPR、計画と規模を持つものすべてが該当します。エフォートは、計画アーティファクト（仕様書、.PR.md、計画が置かれているもの）と初期見積もりが存在した時点から存在します。それ以前は、まだ記録すべきものはありません。
Slice（スライス） — エフォートの一部で、通常はサブPRです。スライスは追加、プルリクエストに対するクローズ、破棄、リネームが行われます。エフォート開始前に追加されたスライスは当初計画の一部であり、開始後に追加されたものはスコープの拡大であり、この2つは記録上区別可能なまま保持されます。
Interval（インターバル） — クロックインされた時間の区間で、通常はスライスに対して行われます。インターバルは手動でクローズされるか、セッション終了時に時計がまだ動いている場合は自動的にクローズされるか、何もクロックインされていなかった場合はコミットタイムスタンプから事後的に導出されます。
Absence（欠勤） — まったく作業しなかった時間。休日、予定、無関係な会議などです。欠勤は事後的に記録され、それが想定されています。欠勤は重なるインターバルから差し引かれます。
Related MCP server: Tempo MCP Server
すべての見積もりはPERTトリプル（楽観値、最頻値、悲観値）であり、抽象的なポイントスケールで与えられ、時間単位では決してありません。期待値と標準偏差は読み出し時にトリプルから導出されます。「見積もりはNである」という単一の数値はどこにも保存されません。なぜなら、裸の数値は、それが事実ではなく見積もりであることを示す不確実性を捨て去ってしまうからです。
ポイントは、手元の作業を同様の形状の過去のエフォートと比較することでアンカーされ、頭の中で感じた時間数をポイントに変換するのではありません。抽象スケールの要点は、実際の期間がまだわからないエフォート同士を、同種のもの同士で比較することにあります。
エフォートは2回見積もられます。
初期見積もりは、最初に書かれた計画に対して、計画が開始したときと同じスライス数で行われます。
最終見積もりは、レトロスペクティブで、実際に結果として得られた計画（途中で挿入されたすべてのスライスを含む）に対して行われます。これは反事実的なものです。「これが実際にどう転んだかを今すべて知っているとしたら、あなたは何と見積もっただろうか？」という問いであり、「どれだけ時間がかかったか？」でも、何かの測定でもありません。
見積もりを2回に分けることで、見積もりが間違う2つの方法を事後に分離できるようになります。初期パスは在庫エラーによって間違う可能性があります。つまり、まだ誰も知らない作業が存在した、または存在すると想定された作業が実際には存在しなかった、という場合です。実際に結果として得られた計画に対して行われる最終パスは、サイズエラーを分離します。つまり、最初から知られていた項目を単に誤って判断した場合です。エフォートごとに単一の数値ではこの2つが混同されますが、パスごとに2つの数値があれば、それらを分離できます。
また、エフォート途中で改訂見積もりを記録することもできます（通常は当初計画にないスライスが挿入されたとき）。レトロスペクティブを待つ必要はありません。
通常の勤務日がデフォルトで想定され、そこからの逸脱のみが記録されます。 クロックインとクロックアウトは例外であり、日常的なものではありません。このツールは毎日8時間ストップウォッチが動いていることを想定していません。具体的には:
手動でクロックされた時間は、それが何時であろうと全額カウントされます。 夜間や週末も含みます。土曜日の22:00にクロックインしたなら、それは実際の時間であり、そのまま記録され、勤務時間の調整は適用されません。
勤務時間モデルは、実際に時間が記録されなかった場所にのみ適用されます。 使用されるのは正確に2か所です:
忘れられたタイマーのクランプ。 セッションが時計がまだ動いたまま終了した場合、インターバルは設定された勤務日の終了時刻（または設定された勤務日・時間外では、固定のセッション長に上限）でクローズされ、無期限に開いたままになったり、分単位で推測されたりすることはありません。
コミットタイムスタンプからのインターバル再構築。 スライスに対して何もクロックインされなかった場合。近接したコミットのクラスターは導出された作業セッションになり、勤務時間モデルを使用して、それらの間のスパンのうちどれだけが作業としてカウントされ、どれだけが一晩のギャップとしてカウントされるかを決定します。
記録された欠勤は、それが重なる任意のインターバル（クロックされたもの、導出されたもの）から差し引かれます。手動でクロックされたインターバルでは全額、導出されたインターバルでは勤務時間モデルを通じて差し引かれます。
MCPサーバーが公開するすべてのツールは、正確に1つのカテゴリに分類されます:
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。見積もりを作成している間、比較用に過去のエフォートを表示します。
status（ステータス） — current。何がクロックインされていて、いつからかを報告します。
calibration（キャリブレーション） — effort_table、effort_detail、summary。蓄積された記録を読み出します。
recording、estimation、statusツールは、期間や集計値を返すことはありません。calibrationツールのみが返すことができます。 これは構造的に強制されます。recording、estimation、statusツールで使用されるすべてのレスポンスモデルは、hours、minutes、duration、wall、average、shareなどの単語を含むフィールド名がないかチェックされ、見つかった場合はチェックが失敗します。
その理由は整理整頓のためではありません。実際の作業時間を見た後に行われた見積もりは、その時間のアンカーされたエコーであり、独立した判断ではありません。あなたが生成する数値は、ちょうど答えを見たばかりであるために汚染されています。汚染ルールにより、見積もりが作成されている間や時計が実行されている間、壁時計の数値がツールのレスポンスに表示されることは決してなく、初期対最終の比較が正直に保たれます。calibrationツールは、見積もりが完了した後に、まさにそれらの数値を報告することが目的であるため、免除されます。
すべてオプションです。すべてにデフォルトがあります。このリストと矛盾する場合は、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。見積もり会話の一部としてのみ意味を持つアクション（エフォートの開始、見積もりの改訂、最終計画の記録、コミットの収穫）は、意図的にMCPツールのみであり、CLIコマンドではありません。それらは、比較可能な過去のエフォートを表示するセッション内で行われることを意図しており、そのコンテキストなしで入力される裸のコマンドではありません。
コード | 意味 |
| 成功。 |
| エラーが発生しました。 |
|
|
以下のいずれもあなたのために実行されていません。以下のコマンドをコピーして自分で実行してください。
MCPサーバーを登録します:
claude mcp add --scope user maestro-estimate -- uv --directory ~/mcp/estimate-maestro run estimate-maestro2つのスキルを個人スキルディレクトリにシンボリックリンクします:
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を設定してください。たとえば他の個人リポジトリと並べて、コミットとプッシュを忘れないようにしやすくするためです。サーバーとシェルの両方から見える必要があるため、両方が読み取る場所（通常はシェルプロファイル）に置いてください。
export ESTIMATE_MAESTRO_STORE=~/somewhere/else2つのフックスクリプトを~/.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" }
]
}
]
}
}すでにhooksブロックがある場合は、~/.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
