Un servidor MCP personal y herramienta de línea de comandos para registrar estimaciones y tiempo real, de modo que las estimaciones puedan eventualmente contrastarse con resultados en lugar de con sensaciones.
Esta es una herramienta de recopilación de datos para la calibración de estimaciones, no un estimador. Nunca estima nada por ti. Registra lo que estimaste para un trabajo, en qué resultó el plan y cuánto tiempo real tomó el trabajo. Qué haces con ese registro — comparar, notar desviaciones, decidir que fuiste sistemáticamente optimista con cierto tipo de trabajo — depende de ti y de lo que lea el almacén más adelante. El trabajo de la herramienta termina en registrar con honestidad.
Cuatro tipos de cosas se registran:
Esfuerzo — una pieza de trabajo que vale la pena seguir por sí misma: un pull request, un mega-PR, cualquier cosa con un plan y un tamaño. Un esfuerzo existe desde el momento en que tiene un artefacto de plan (una especificación, un .PR.md, donde sea que viva el plan) y una estimación inicial. Antes de ese punto no hay nada que registrar todavía.
Segmento — una pieza de un esfuerzo, normalmente un sub-PR. Los segmentos se añaden, se cierran contra un pull request, se descartan o se renombran. Un segmento añadido antes de que el esfuerzo comience es parte del plan original; uno añadido después es crecimiento de alcance, y ambos se mantienen distinguibles en el registro.
Intervalo — un período de tiempo registrado, normalmente contra un segmento. Los intervalos se cierran manualmente, se cierran automáticamente cuando una sesión termina con el reloj aún en marcha, o se derivan a posteriori de las marcas de tiempo de los commits cuando no se registró nada en absoluto.
Ausencia — tiempo que no se trabajó en absoluto: un día festivo, una cita, una reunión no relacionada. Las ausencias se registran de forma retroactiva y se espera que así sea. Restan de cualquier intervalo que solapen.
Related MCP server: Tempo MCP Server
Cada estimación es una tripla PERT — optimista, probable, pesimista — dada en una escala abstracta de puntos, nunca en horas. El valor esperado y la desviación estándar se derivan de la tripla al leer; nada almacena un único número "la estimación es N", porque un número desnudo descarta la incertidumbre que la convertía en una estimación en lugar de un hecho.
Los puntos se anclan comparando el trabajo en cuestión con esfuerzos previos de forma similar, no convirtiendo un número sentido de horas en puntos en tu cabeza. El sentido de una escala abstracta es comparar cosas semejantes entre esfuerzos cuya duración real aún no conoces.
Un esfuerzo se estima dos veces:
La estimación inicial, hecha contra el plan tal como se escribió por primera vez, con el mismo número de segmentos con el que comenzó el plan.
La estimación final, hecha en la retrospectiva contra el plan tal como resultó realmente — incluyendo cada segmento insertado en el camino. Esta es una contrafactual: "dado todo lo que ahora sabes sobre cómo resultó esto realmente, ¿qué habrías estimado?" — nunca "¿cuánto tardó?", y nunca una medición de nada.
Dividir la estimación en dos pasadas es lo que hace que las dos formas en que una estimación puede fallar sean separables a posteriori. La pasada inicial puede fallar por error de inventario — existía trabajo que nadie conocía todavía, o trabajo que se asumía existente resultó no existir. La pasada final, hecha contra el plan tal como resultó realmente, aísla el error de dimensionamiento — los elementos que se conocían desde el principio y simplemente se juzgaron mal. Un único número por esfuerzo confunde ambos; dos números, uno por pasada, los mantienen separados.
También se puede registrar una estimación revisada a mitad del esfuerzo — típicamente cuando se inserta un segmento que no estaba en el plan original — sin esperar a la retrospectiva.
Se asume un día laboral normal por defecto, y solo se registran las desviaciones de él. Registrar entrada y salida es la excepción, no la rutina — la herramienta no espera un cronómetro corriendo ocho horas cada día. Concretamente:
El tiempo registrado manualmente cuenta en su totalidad, sean cuales sean las horas en que caiga. Tardes y fines de semana incluidos: si registraste entrada a las 22:00 un sábado, eso es tiempo real y se registra como tal, sin ajuste de horas laborales aplicado.
El modelo de horas laborales solo se aplica donde no se registró tiempo realmente. Hay exactamente dos lugares donde se usa:
Limitar un temporizador olvidado. Si una sesión termina con el reloj aún en marcha, el intervalo se cierra al final configurado del día laboral (o, fuera de los días y horas laborales configurados, se limita a una duración fija de sesión) en lugar de permanecer abierto indefinidamente o adivinarse al minuto.
Reconstruir intervalos a partir de marcas de tiempo de commits cuando nunca se registró nada para un segmento. Un grupo de commits cercanos se convierte en una sesión de trabajo derivada, usando el modelo de horas laborales para decidir cuánto del lapso entre ellos cuenta como trabajo en lugar de un hueco nocturno.
Una ausencia registrada sobre un lapso resta de cualquier intervalo — registrado o derivado — que solape, en su totalidad para un intervalo registrado manualmente y a través del modelo de horas laborales para uno derivado.
Cada herramienta que expone el servidor MCP cae exactamente en una categoría:
registro — 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.
estimación — reference_efforts, que muestra esfuerzos previos para comparación mientras se hace una estimación.
estado — current, que informa de qué está registrado y desde cuándo.
calibración — effort_table, effort_detail, summary, que leen el registro acumulado.
Las herramientas de registro, estimación y estado nunca devuelven una duración o un agregado. Solo las de calibración pueden. Esto se aplica estructuralmente: cada modelo de respuesta usado por una herramienta de registro, estimación o estado se comprueba en busca de nombres de campo que contengan palabras como hours, minutes, duration, wall, average o share, y la comprobación falla si se encuentra una.
La razón no es el orden. Una estimación hecha después de ver la duración real del trabajo es un eco anclado de esa duración, no un juicio independiente — el número que producirías está contaminado por haber visto la respuesta justo antes. La regla de contaminación evita que una cifra de tiempo real aparezca en una respuesta de herramienta mientras se hace una estimación o se ejecuta un reloj, de modo que la comparación inicial-versus-final se mantenga honesta. Las herramientas de calibración están exentas porque su propósito completo es informar exactamente de esas cifras, una vez que la estimación ha terminado.
Todas son opcionales; cada una tiene un valor por defecto. Lee de src/estimate_maestro/config.py, no de esta lista, si ambos discrepan.
Variable | Valor por defecto | Significado |
|
| Ruta al directorio del almacén. |
|
| Inicio del día laboral (hora ISO 8601). |
|
| Fin del día laboral (hora ISO 8601). |
|
| Inicio de la pausa diaria de almuerzo, excluida de los segundos laborales. |
|
| Fin de la pausa diaria de almuerzo. |
|
| Días de la semana separados por comas contados como laborales (lunes |
|
| Duración máxima asignada a una sesión limitada que comienza fuera de la ventana de horas laborales. |
|
| Tiempo añadido antes del commit más temprano en una sesión derivada, para cubrir trabajo hecho antes del primer commit. |
|
| Hueco de tiempo laboral entre commits más allá del cual se considera que una sesión derivada ha terminado y ha comenzado una nueva. |
|
| Número mínimo de esfuerzos registrados antes de que |
ESTIMATE_MAESTRO_DERIVE_LEAD_IN_MINUTES no debe exceder ESTIMATE_MAESTRO_DERIVE_SESSION_GAP_MINUTES; el servidor se niega a iniciar en caso contrario.
estimate-maestro-cli cubre las acciones de registro cotidianas que no necesitan una conversación: clock-in, clock-out, current, record-absence, effort-table y summary. Las acciones que solo tienen sentido como parte de una conversación de estimación — iniciar un esfuerzo, revisar una estimación, registrar el plan final, cosechar commits — son solo herramientas MCP, no comandos CLI, a propósito: están pensadas para ocurrir dentro de una sesión que muestre esfuerzos previos comparables, no como un comando desnudo escrito sin ese contexto.
Código | Significado |
| Éxito. |
| Ocurrió un error. |
| Solo |
Ninguno de los siguientes pasos se ha ejecutado por ti — copia los comandos de abajo y ejecútalos tú mismo.
Registra el servidor MCP:
claude mcp add --scope user maestro-estimate -- uv --directory ~/mcp/estimate-maestro run estimate-maestroCrea un enlace simbólico de las dos habilidades en tu directorio personal de habilidades:
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-workConvierte el almacén en un repositorio git. Sus archivos son texto plano y de solo añadidura, de modo que se pueda hacer commit y viajar entre máquinas, y es la única copia superviviente de lo que registra: un número perdido o incorrecto allí no se puede reconstruir desde ningún otro lugar. Mantenlo privado: contiene nombres de proyectos, nombres de ramas y cuánto tiempo llevaron las cosas, nada de lo cual pertenece a un repositorio público.
mkdir -p ~/.local/share/estimate-maestro
git -C ~/.local/share/estimate-maestro initLa ubicación predeterminada del almacén sigue la especificación XDG Base Directory Specification y no necesita configuración. Establece ESTIMATE_MAESTRO_STORE solo si quieres el almacén en otro lugar, por ejemplo junto a tus otros repositorios personales, para que sea más fácil recordar hacer commit y push. Debe ser visible tanto para el servidor como para tu shell, así que colócalo donde ambos lo lean (normalmente tu perfil de shell):
export ESTIMATE_MAESTRO_STORE=~/somewhere/elseConecta los dos scripts de hook en ~/.claude/settings.json: hooks/session-end.sh como hook de SessionEnd (cierra un temporizador olvidado, limitado al día laborable configurado) y hooks/session-start.sh como hook de SessionStart (informa si ya hay un temporizador en ejecución):
{
"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" }
]
}
]
}
}Fusiona eso en el bloque hooks existente en ~/.claude/settings.json en lugar de sobrescribirlo, si ya hay uno.
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
