Skip to main content
Glama

Alcoven

by co.alcoven
OverviewDiscussionsAdmin

Read from the project

read
Read-only

Opens, shows or reads what a document, a section, a task, a note or a file says, word for word, with who wrote it and when; a text file or code by its lines. A document of several sections is read one section at a time: its own address answers with its title and its sections, each with its § address. A text file comes with its line numbers (12| ...), at most 400 lines at a time; offset goes on from a line, and an address ending #L10-24 gives those lines. The numbers are not part of the text. A Word file, a spreadsheet or slides come as the text of their preview. Any other file comes as what it is and a link to open it in Alcoven: its bytes are not read. For a .view.md, the view as this person sees it: each block's reading with its § address, a rows block's first five rows, and what each form adds a row to. For a .focus.md, the project's plan as this person sees it: its phases with how each stands and the current one's objectives, this week's number and things with their tasks, and the gaps set aside, then the file. A Google Sheets source whose rows are shown answers with its rows from the last fetch, 100 at a time, newest last; offset is then the sheet row to start at.

Input Schema

NameRequiredDescriptionDefault
limitNoLines to return. Default 300.
offsetNoLine to start at, from a previous read.
addressYesA § address from Alcoven, like acme/research/pricing.md, acme/research/pricing.md#findings or acme/src/app.ts#L10-24. The leading § is optional.
projectNoThe project's slug, from open_project, like acme. Not needed when a § address names the project, or when the person is on one project.

Output Schema

NameRequiredDescriptionDefault
atYes
toYes
viaYes
fileNo
fromYes
kindYes
textYes
viewNo
focusNo
totalYes
agreedNo
authorYes
sourceNo
widgetNo
addressYes
widgetsNo
scheduleNo
sectionsNo
nextOffsetYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / view / properties / blocks / items / properties / lines
      Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  2. Changed1 schema field changed
    • addedOutput schema / properties / focus
      Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "address": {
+      "type": "string"
+    },
+    "built": {
+      "anyOf": [
+        {
+          "additionalProperties": {},
+          "properties": {
+            "closed": {
+              "type": "boolean"
+            },
+            "kept_by": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "moves_it": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "now": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "pace": {
+              "anyOf": [
+                {
+                  "additionalProperties": {},
+                  "properties": {
+                    "by": {
+                      "type": "string"
+                    },
+                    "days_left": {
+                      "type": "number"
+                    },
+                    "days_since": {
+                      "type": "number"
+                    },
+                    "early": {
+                      "type": "boolean"
+                    },
+                    "met": {
+                      "type": "boolean"
+                    },
+                    "needed": {
+                      "type": "number"
+                    },
+                    "now": {
+                      "type": "number"
+                    },
+                    "on_pace": {
+                      "type": "boolean"
+                    },
+                    "per": {
+                      "type": "string"
+                    },
+                    "rise": {
+                      "type": "boolean"
+                    },
+                    "sentence": {
+                      "type": "string"
+                    },
+                    "so_far": {
+                      "type": "number"
+                    },
+                    "target": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "target",
+                    "by",
+                    "now",
+                    "met",
+                    "needed",
+                    "so_far",
+                    "per",
+                    "rise",
+                    "early",
+                    "days_since",
+                    "days_left",
+                    "on_pace",
+                    "sentence"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "path": {
+              "type": "string"
+            },
+            "reading": {
+              "type": "string"
+            },
+            "title": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "path",
+            "title",
+            "closed",
+            "reading",
+            "now",
+            "pace",
+            "moves_it",
+            "kept_by"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "kept_by": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "notes": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "phases": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "date_passed": {
+            "type": "boolean"
+          },
+          "days_left": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "ended": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "from": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "met": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "n": {
+            "type": "number"
+          },
+          "objectives": {
+            "items": {
+              "anyOf": [
+                {
+                  "additionalProperties": {},
+                  "properties": {
+                    "closed": {
+                      "type": "boolean"
+                    },
+                    "kind": {
+                      "const": "number",
+                      "type": "string"
+                    },
+                    "met": {
+                      "type": [
+                        "boolean",
+                        "null"
+                      ]
+                    },
+                    "now": {
+                      "type": [
+                        "number",
+                        "null"
+                      ]
+                    },
+                    "pace": {
+                      "anyOf": [
+                        {
+                          "additionalProperties": {},
+                          "properties": {
+                            "by": {
+                              "type": "string"
+                            },
+                            "days_left": {
+                              "type": "number"
+                            },
+                            "days_since": {
+                              "type": "number"
+                            },
+                            "early": {
+                              "type": "boolean"
+                            },
+                            "met": {
+                              "type": "boolean"
+                            },
+                            "needed": {
+                              "type": "number"
+                            },
+                            "now": {
+                              "type": "number"
+                            },
+                            "on_pace": {
+                              "type": "boolean"
+                            },
+                            "per": {
+                              "type": "string"
+                            },
+                            "rise": {
+                              "type": "boolean"
+                            },
+                            "sentence": {
+                              "type": "string"
+                            },
+                            "so_far": {
+                              "type": "number"
+                            },
+                            "target": {
+                              "type": "number"
+                            }
+                          },
+                          "required": [
+                            "target",
+                            "by",
+                            "now",
+                            "met",
+                            "needed",
+                            "so_far",
+                            "per",
+                            "rise",
+                            "early",
+                            "days_since",
+                            "days_left",
+                            "on_pace",
+                            "sentence"
+                          ],
+                          "type": "object"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "path": {
+                      "type": "string"
+                    },
+                    "target": {
+                      "anyOf": [
+                        {
+                          "additionalProperties": {},
+                          "properties": {
+                            "by": {
+                              "type": "string"
+                            },
+                            "value": {
+                              "type": "number"
+                            }
+                          },
+                          "required": [
+                            "value",
+                            "by"
+                          ],
+                          "type": "object"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "title": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "kind",
+                    "path",
+                    "title",
+                    "closed",
+                    "target",
+                    "now",
+                    "met",
+                    "pace"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "additionalProperties": {},
+                  "properties": {
+                    "closed": {
+                      "type": "boolean"
+                    },
+                    "kind": {
+                      "const": "task",
+                      "type": "string"
+                    },
+                    "met": {
+                      "type": "boolean"
+                    },
+                    "task": {
+                      "anyOf": [
+                        {
+                          "additionalProperties": {},
+                          "properties": {
+                            "address": {
+                              "type": "string"
+                            },
+                            "for": {
+                              "type": [
+                                "string",
+                                "null"
+                              ]
+                            },
+                            "state": {
+                              "type": "string"
+                            },
+                            "title": {
+                              "type": "string"
+                            }
+                          },
+                          "required": [
+                            "address",
+                            "title",
+                            "state",
+                            "for"
+                          ],
+                          "type": "object"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "words": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "kind",
+                    "words",
+                    "closed",
+                    "met",
+                    "task"
+                  ],
+                  "type": "object"
+                }
+              ]
+            },
+            "type": "array"
+          },
+          "of": {
+            "type": "number"
+          },
+          "state": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "until": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "n",
+          "title",
+          "from",
+          "until",
+          "state",
+          "date_passed",
+          "days_left",
+          "met",
+          "of",
+          "ended",
+          "objectives"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "problems": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "read": {
+      "type": "boolean"
+    },
+    "read_back": {
+      "type": "string"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "set_aside": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "by": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "day": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "gap": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "gap",
+          "reason",
+          "by",
+          "day"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "title": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    },
+    "week": {
+      "anyOf": [
+        {
+          "additionalProperties": {},
+          "properties": {
+            "done": {
+              "type": "number"
+            },
+            "items": {
+              "items": {
+                "additionalProperties": {},
+                "properties": {
+                  "closed": {
+                    "type": "boolean"
+                  },
+                  "done": {
+                    "type": "boolean"
+                  },
+                  "due": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "n": {
+                    "type": "number"
+                  },
+                  "task": {
+                    "anyOf": [
+                      {
+                        "additionalProperties": {},
+                        "properties": {
+                          "address": {
+                            "type": "string"
+                          },
+                          "for": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "state": {
+                            "type": "string"
+                          },
+                          "title": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "address",
+                          "title",
+                          "state",
+                          "for"
+                        ],
+                        "type": "object"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "when": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "words": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "n",
+                  "words",
+                  "when",
+                  "due",
+                  "closed",
+                  "done",
+                  "task"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "line": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "number": {
+              "anyOf": [
+                {
+                  "additionalProperties": {},
+                  "properties": {
+                    "closed": {
+                      "type": "boolean"
+                    },
+                    "kept_by": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "moves_it": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "now": {
+                      "type": [
+                        "number",
+                        "null"
+                      ]
+                    },
+                    "pace": {
+                      "anyOf": [
+                        {
+                          "additionalProperties": {},
+                          "properties": {
+                            "by": {
+                              "type": "string"
+                            },
+                            "days_left": {
+                              "type": "number"
+                            },
+                            "days_since": {
+                              "type": "number"
+                            },
+                            "early": {
+                              "type": "boolean"
+                            },
+                            "met": {
+                              "type": "boolean"
+                            },
+                            "needed": {
+                              "type": "number"
+                            },
+                            "now": {
+                              "type": "number"
+                            },
+                            "on_pace": {
+                              "type": "boolean"
+                            },
+                            "per": {
+                              "type": "string"
+                            },
+                            "rise": {
+                              "type": "boolean"
+                            },
+                            "sentence": {
+                              "type": "string"
+                            },
+                            "so_far": {
+                              "type": "number"
+                            },
+                            "target": {
+                              "type": "number"
+                            }
+                          },
+                          "required": [
+                            "target",
+                            "by",
+                            "now",
+                            "met",
+                            "needed",
+                            "so_far",
+                            "per",
+                            "rise",
+                            "early",
+                            "days_since",
+                            "days_left",
+                            "on_pace",
+                            "sentence"
+                          ],
+                          "type": "object"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "path": {
+                      "type": "string"
+                    },
+                    "reading": {
+                      "type": "string"
+                    },
+                    "title": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "path",
+                    "title",
+                    "closed",
+                    "reading",
+                    "now",
+                    "pace",
+                    "moves_it",
+                    "kept_by"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "state": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "week_of": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "week_of",
+            "state",
+            "number",
+            "done",
+            "line",
+            "items"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "title",
+    "address",
+    "url",
+    "reason",
+    "kept_by",
+    "read",
+    "read_back",
+    "problems",
+    "notes",
+    "phases",
+    "week",
+    "set_aside",
+    "built"
+  ],
+  "type": "object"
+}
  3. Changed1 schema field changed
    • changedOutput schema / required
      Previous value: -[
-  "address",
-  "kind",
-  "author",
-  "at",
-  "via",
-  "text",
-  "from",
-  "to",
-  "total",
-  "nextOffset",
-  "schedule"
-]New value: +[
+  "address",
+  "kind",
+  "author",
+  "at",
+  "via",
+  "text",
+  "from",
+  "to",
+  "total",
+  "nextOffset"
+]
  4. Changed5 schema fields changed
    • addedOutput schema / properties / schedule
      Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "address": {
+      "type": "string"
+    },
+    "does": {
+      "type": "string"
+    },
+    "next": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "owner": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "paused": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "problems": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "runs": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "at": {
+            "type": "string"
+          },
+          "said": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "at",
+          "said"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "title": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    },
+    "when": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "zone": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "title",
+    "address",
+    "reason",
+    "when",
+    "zone",
+    "next",
+    "does",
+    "owner",
+    "paused",
+    "runs",
+    "problems",
+    "url"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / view / properties / acts
      Added value: +{
+  "items": {
+    "additionalProperties": {},
+    "properties": {
+      "address": {
+        "type": "string"
+      },
+      "adds_to": {
+        "type": "string"
+      },
+      "columns": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "kind": {
+        "type": "string"
+      },
+      "table": {
+        "type": "string"
+      },
+      "title": {
+        "type": "string"
+      },
+      "tool": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "title",
+      "kind",
+      "address",
+      "adds_to",
+      "table",
+      "columns",
+      "tool"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / view / properties / blocks / items / properties / rows
      Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "columns": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "count": {
+      "type": "number"
+    },
+    "first": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "cells": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "row": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "row",
+          "cells"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "count",
+    "columns",
+    "first"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / view / properties / filters
      Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedOutput schema / required
      Previous value: -[
-  "address",
-  "kind",
-  "author",
-  "at",
-  "via",
-  "text",
-  "from",
-  "to",
-  "total",
-  "nextOffset"
-]New value: +[
+  "address",
+  "kind",
+  "author",
+  "at",
+  "via",
+  "text",
+  "from",
+  "to",
+  "total",
+  "nextOffset",
+  "schedule"
+]
  5. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavior: line numbers are not part of the text, binary/Office files return a preview or a link rather than bytes, capped at 400 lines or 100 rows. It stops short of stating failure modes, but the added context is substantial.

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

Conciseness3/5

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

The purpose is front-loaded, but the whole definition is one enormous semicolon-chained sentence mixing purpose, per-format behavior and pagination, which makes it hard to scan. Every clause carries information, yet the formatting works against the reader.

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

Completeness4/5

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

Given four parameters and a full output schema, the description goes well beyond the required minimum by covering each address type (.md sections, plain text, Office previews, .view.md, .focus.md, Google Sheets rows). Only error/empty-address behavior and the relationship to grep/search are absent.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely extends the parameters: it explains that 'offset goes on from a line', that '#L10-24 gives those lines', and that offset means a sheet row when reading a Google Sheets source. That resolves the ambiguity the schema alone leaves.

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

Purpose4/5

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

Opens with a concrete verb list and resource list ('Opens, shows or reads what a document, a section, a task, a note or a file says, word for word'), so an agent knows this is the content-retrieval tool. It does not explicitly contrast itself with siblings like grep or search, which read text too, so the boundary is left to inference.

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

Usage Guidelines3/5

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

Usage rules are implied rather than stated: 'A document of several sections is read one section at a time' and the different pagination semantics per file type tell the agent how to sequence calls. There is no explicit when-to-use/when-not or named alternative (grep, search, part), which is the main gap.

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

All Alcoven toolsInspect
Try in Browser
Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources