projectstate

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

With no annotations, the description carries the full burden. It usefully discloses that the tool may create a project if it doesn't exist (a side effect) and what the brief contains, but says nothing about permissions, idempotency, or what creation does with name/description.

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?

Three dense sentences, front-loaded with the primary action and return content before the listing mode and slug syntax. Nothing is wasted, though the slug-format detail could be folded in more tightly.

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?

An output schema exists, so return values need not be re-explained, and the listing mode is covered. However, for a tool that can create, the roles of `name` versus `project` and `description` remain unresolved, leaving an agent guessing how to initialize a new project.

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 exposes bare titles (Name, Project, Description). The description compensates for `project` by giving the slug format and omission semantics, but leaves `name` and `description` entirely unexplained, likely the creation fields.

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 and resource ('Open (or create) a project') and enumerates the returned brief (status line, open tasks, decisions, failed attempts), which is far more than a restated title. It does not explicitly name siblings like project_status, so differentiation 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.

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

'Call this first in a session' gives a clear entry-point condition, and 'Omit `project` to list your projects' describes the alternate mode of use. No sibling alternatives (project_status, recall) are named or contrasted, so it stops short of full when/when-not guidance.

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

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

With no annotations the description must carry the full burden, and it does disclose meaningful traits: the operation is cheap, it is a read by default, and set_status explicitly overwrites (destroys) the existing status line, with an example of the format. It omits permissions/auth requirements and whether other project state is affected.

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?

Three short sentences, front-loaded with the read purpose, followed by the write mode and the usage rationale; the inline example earns its space by fixing the expected value format. No 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?

An output schema exists, so return contents need not be explained (the description describes them anyway). The dual read/write nature, cost and intended use are covered; only the 'project' parameter's semantics and any permission/error behavior remain unaddressed.

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 explains set_status well, including a concrete example value, but says nothing about the required 'project' parameter beyond what its name implies, leaving half the parameters undocumented in both schema and prose.

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 ('Get') and resource ('the project's one-line status, open tasks and last change'), and even enumerates the returned fields, plus the secondary write mode via set_status. It does not explicitly distinguish itself from siblings like project_open, recall, remember or update, which keeps it out of the top band.

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?

"Cheap; use it for handoff notes between sessions" gives clear usage context and the set_status example implies when to write versus read. There are no explicit when-not conditions and no named alternatives among the overlapping siblings (recall/remember), so it stops short of 5.

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

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

With no annotations, the description carries the behavioral burden and does disclose non-obvious traits: result ranking (active first, superseded last) and character-based trimming to `max_chars`. It omits edge behavior (empty results, interaction of `limit` with trimming, permission/rate considerations), keeping it below top marks.

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?

Four tightly packed sentences, front-loaded with the core action and result semantics, then filters, then the recency case, then follow-ups. Dense but nearly every clause carries distinct information; minor density cost from the inline enum list.

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?

An output schema exists, so return formatting need not be described, and the description supplies the ranking/trimming behavior an agent needs. For an 8-parameter tool at 0% schema coverage, only `limit` semantics and no-match behavior are left unaddressed.

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, and it largely does: it explains `query` semantics (keywords, omission = recent entries), `max_chars` trimming, filter params (status, tags, files), and supplies enum values for `kind` (decision|attempt|task|note) that the schema itself lacks. It leaves `limit` and `project` undocumented, so it is not fully compensating.

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+resource ('Search the project's memory') and adds scope detail: returns a few ranked entries, active before superseded, trimmed to max_chars. It never explicitly names what it is NOT (e.g. a sibling retrieval tool), so sibling differentiation is only implied by the follow-up mention of update/remember.

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?

Gives concrete operating guidance: use 2-5 specific keywords, omit `query` to get the most recent entries, and follow up with update() or remember(). It does not spell out when-not-to-call or an alternative search path, but the practical context is clear and actionable.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses deduplication ('Identical content is stored once, so retries are safe') and billing/idempotency semantics for idempotency_key. It does not mention permissions or what superseding does to the older record beyond marking it replaced, leaving a small 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?

It is a dense but well-front-loaded paragraph: the core action leads, then each parameter's semantic role follows in a logical order. Every sentence adds information, though the block format rather than a list makes it slightly harder to scan for a 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?

An output schema exists, so return values need not be explained, and the description focuses correctly on input semantics and side effects. For a 9-parameter mutation tool with zero schema coverage, it covers most of what an agent needs, missing only project/tags semantics and any note on required-field behavior.

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, and it largely does: kind enumerants with meanings, title as one line, body for details/reasons/errors, files as related paths, supersedes as replacement marking, and idempotency_key semantics. It leaves project, tags, and the exact status values per kind only partially explained (project and tags unexplained), so not a full 5.

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 opens with a specific verb+resource: 'Store one fact about the project.' It clearly distinguishes the semantic content being stored (facts with kinds) rather than just restating the name 'remember.' It does not explicitly contrast with siblings like recall or update, but the purpose is 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 kind taxonomy (decision/attempt/task/note) implicitly guides what to store, and status values per kind are given. However, there is no explicit when-to-use-this-vs-recall-or-update guidance, and no stated preconditions (e.g., does the project need to exist first via project_open?). Usage is inferable but not framed as guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses that title/body/tags/files are replaced (not merged), that append adds a line, and that delete is a boolean flag rather than a separate tool. It does not disclose mutation semantics for omitted fields, whether status transitions are validated, permission requirements, or reversibility.

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 dense sentence, front-loaded with the core action and id-scoped subject, followed by a parenthesized enumeration of operations. No filler or 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?

An output schema exists, so return values need no explanation, and the description does add the missing enum values for status. However, for a 9-parameter mutation tool with no annotations, the required `project` argument and any permission/error behavior remain undocumented, leaving 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?

Schema coverage is 0%, so the description must compensate, and it does well: it lists valid status values per entry kind (which the schema does not define as enums at all), and explains title, body, append, tags, files, and delete. The gap is the required `project` parameter, which is never mentioned.

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 ('Change') and resource ('an existing entry by id') and enumerates the mutation modes (status, title/body, append, tags/files, delete). It is clearly distinguishable from siblings like remember/recall, though it never explicitly contrasts with them.

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?

Usage is only implied: 'Change an existing entry by id' suggests this is the tool for modifying existing entries rather than creating new ones. There is no explicit guidance on when to prefer this over remember or on which alternate tool handles creation of new entries.

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