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

No annotations are provided, so the description carries the burden. It discloses the 'Globally unique' constraint, which is behavioral. However, it doesn't state what happens on conflict (error? overwrite?), whether aliases are reversible/removable, or any side effects on already-resolved references. With zero annotations, more disclosure would be expected (e.g., does adding an alias affect existing resolve calls?).

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?

Two sentences plus an example — compact and front-loaded with the primary purpose first. The example is essential and earns its place by clarifying parameter roles. Minor waste: no heading/labels separate example from description, but it reads clearly. Could arguably be even tighter.

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 simple 2-param tool with an output schema present, the description is reasonably complete. The example demonstrates a realistic usage pattern tying in resolve_ref. Gaps: no mention of error handling for non-existent refs or existing aliases, and no global-uniqueness behavior details beyond the statement. But given the low complexity and that the output schema exists, the coverage is adequate.

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 does via the example. The example clarifies that 'ref' is the target entity (component:api-gateway) and 'alias' is the short nickname (gw), plus shows the aliases are usable in resolve_ref. This adds real semantic meaning beyond the bare schema field names. Could be improved with format expectations (e.g., valid alias characters), but the example handles the core semantics well.

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 purpose: 'Add a short nickname for an entity' with the constraint 'Globally unique.' The verb 'Add' plus resource 'alias for an entity' is specific. It doesn't explicitly distinguish from its sibling remove_alias, but the action itself is clear enough. The example reinforces the purpose with a concrete usage.

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 implies usage context: creating short nicknames for entities to enable shorter references. The example showing add_alias followed by resolve_ref demonstrates the intended workflow. However, it doesn't explicitly state when NOT to use this tool or mention alternatives (e.g., when to use remove_alias for cleanup), and doesn't cover constraints beyond global uniqueness (charset, length limits, what happens on duplicate).

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?

No annotations are provided, so the description carries the behavioral burden. It discloses the effect ('automatically included in every task pack'), which explains the consequence of adding a ref. However, it doesn't reveal whether the operation is additive/merge, idempotent, reversible, or what happens if the ref already exists. It also doesn't state auth or permission requirements.

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 sentences, front-loaded with the core action and the key behavioral consequence. The typical-use line adds value without bloat. No wasted words, though the structure could arguably place the typical-use line first for quicker skimming.

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 explains core purpose and consequence, but for a governance-affecting mutation tool with no annotations, it's somewhat thin. It doesn't address edge cases (duplicate refs, invalid refs) or clarify whether the change is immediately effective or requires reindexing. An output schema exists, which relieves the return-format burden, but the absence of behavioral depth keeps this from being fully 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?

Schema coverage is 0%, but there is only one parameter (ref) and its meaning is reasonably inferable from the tool purpose. The description does not add syntax, format, or validation details for ref beyond the schema's type:string, so it doesn't add substantial value over the schema. With a single well-named param and 0% coverage, a baseline of 3 is fair.

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 (add) and resource (a ref to the always_include list), and explains what the list does ('Any ref in this list is automatically included in every task pack'). It distinguishes this from siblings like add_external_ref and add_governance by naming the specific destination list, though it doesn't explicitly differentiate from the sibling tools.

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 a clear typical use case ('a personal-prefs governance entity you want everywhere'), which signals when to use it. However, it doesn't mention when NOT to use it or name alternatives (remove_always_include for removal, add_governance/add_external_ref for other ref types), leaving the when-not guidance implicit.

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?

No annotations are provided, so the description carries full burden. It transparently discloses that the tool only stores pointers and does not fetch external state — key behavioral context that prevents misuse. The only minor gap is no mention of idempotency, overwrite behavior, or what happens if the ref already exists, though the 'stores pointers' framing covers the core constraint.

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?

Two sentences, zero waste. The first sentence states the action with example systems, the second delivers critical caveat and alternative guidance. Every word earns its place.

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 simple 4-param tool with 100% schema coverage and an output schema, the description fully covers purpose, limitation, and usage alternative. The tool is straightforward (store a pointer), and the description handles it completely.

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 100%, so the schema already describes all 4 parameters well. The description adds value by framing what the stored data represents (a pointer to external state) and clarifies the semantic intent: this is for cross-system references. The description does not list params in prose, but the schema is thorough (including the optional url with default), so the baseline holds with minor added 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 clearly states the verb+resource: 'Attach a reference to an external tracking system' with explicit examples (Jira, GitHub). The first sentence is concise and specific, and it distinguishes from sibling tools like remove_external_ref, which handles the inverse 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?

The description explicitly states when NOT to use this for fetching state: 'ContextForge does not fetch these — it just stores pointers. Use a separate MCP server (Atlassian, GitHub, etc.) to retrieve current state.' This is excellent guidance on the tool's limitations and points to alternatives for the broader workflow.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description usefully reveals the cascading behavior for repos, the direct-link behavior for tasks, and the governance-to-governance prohibition. However, it doesn't disclose side effects like whether removing the link destroys the reference, whether governance refs can be overridden by re-attaching, or what the return value/response looks like. Adequate but not rich.

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 compact, using a clear opening sentence followed by two focused sentences explaining behavior and constraints. Every sentence earns its place. Could be slightly more efficient by merging context, but it's well-structured and front-loaded with 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?

The tool is a mutation with no annotations, zero schema description coverage, and only minimal parameter semantics. An output schema exists (which covers return values). The description covers purpose, the inclusion behavior in task packs, and the cascading/entity constraint. However, for a mutation tool it lacks disclosure about reversibility (remove_governance exists but the behavior isn't connected), overwrite semantics, or any prerequisite conditions. Adequate but leaves meaningful gaps.

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 parameter meaning. The description implies that 'ref' identifies a component/repo/task and 'governance_ref' is the governance to attach, but it doesn't explicitly define either parameter's syntax, format, or allowed entity types. The opening line names the target entity types, which is helpful, but the distinction between the two refs is implicit rather than explicit.

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 a clear resource ('governance ref to a component/repo/task'). It differentiates from siblings by noting it cannot attach governance to another governance entity, and the sibling remove_governance clearly represents the inverse operation. However, it doesn't explicitly name the sibling alternatives, which would push it to 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?

The description explains when the governance content is included ('in any task pack that touches this entity'), which clarifies the practical effect. It also gives an explicit exclusion ('Cannot attach governance to another governance entity'). It lacks explicit 'when not to use' or named alternatives, but the cascade and direct-attach distinction provides useful context for choosing this tool.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses that it separates appended content with a blank line, and that it will create the subtopic if missing. However, it doesn't disclose what happens to existing content on append failure, whether the operation is idempotent, or what the return/response format is since there is an output schema.

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 appropriately short — two sentences, minimal waste. The key operational detail (blank line separation) is included in the second sentence. It could arguably be a 5, but the brevity leaves room for adding more meaningful content, so the conciseness is good but the efficiency comes at the cost of missing parameter clarity.

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?

There is an output schema present, so return value explanation isn't required. However, with 0% schema coverage on 2 parameters, no annotations, and no guidance on ref syntax or content format, the documentation is incomplete. The blank-line behavior is disclosed but many operational details (failure modes, idempotency, ordering guarantees) are absent. For a tool with two required params and an output schema, this is a minimum viable description.

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%, meaning neither 'ref' nor 'content' has schema-level descriptions. The description does not explain what 'ref' refers to (a subtopic reference evidently) or what format 'content' should take. 'Creating it if missing' implies ref points to a subtopic, but no syntax, format, or constraints are given for either parameter. The description fails to compensate for the zero 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 is clear: 'Append content to a subtopic, creating it if missing' is a specific verb+resource with a clear operation. It distinguishes from upsert_context (an upsert overwrites/replaces) by specifying 'append' (add to existing) and 'creating if missing.' However, it doesn't explicitly contrast with siblings like get_context or import_content.

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 states what it does but not explicitly when to use it vs alternatives. The distinction from upsert_context (append vs upsert) is implied through the verb 'append.' There's no explicit 'use this when' language or mention of alternatives, though the append-vs-create semantics provide some guidance on when this is appropriate.

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?

No annotations are provided, so the description carries the full burden. It discloses the side-effect (persistent binding recorded so get_current_workspace can read it) and the constraint that the path must come from the Roots capability. However, it doesn't state whether binding overwrites an existing binding, whether it's destructive, or whether it requires any special permissions.

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 paragraphs, front-loaded with the core action, followed by effect and context. No wasted sentences, though the formatting with blank lines is slightly heavier than needed.

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 an output schema, so return values are covered elsewhere. For a state-mutating tool with no annotations, the description covers the mechanism and downstream effect reasonably. But it omits details like whether binding is overwrite or idempotent, and given the 'bind' semantic, a note on reversibility (unbind_workspace) would strengthen completeness.

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 schema only provides types, not meaning. The description explains the 'path' parameter's origin (from Roots capability) but doesn't elaborate on 'repo_slug' format expectations or validation beyond what's in the schema. It adds some value but could be richer.

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 a specific verb+resource ('Associate a local workspace path with a repo slug'). It also explains the downstream effect (get_current_workspace returns the slug) which distinguishes it from siblings like unbind_workspace and get_current_workspace.

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 explains WHY to bind (so the LLM can auto-select relevant context) and that the Roots capability is the canonical source of the path. It doesn't explicitly state when NOT to use it or name alternatives, but the context is clear and useful.

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?

No annotations are provided, so the description must carry the behavioral transparency burden. It only states 'Create a new Component entity' and explains the kind tag's filtering purpose; there is no disclosure of idempotency, duplicate handling, required permissions, or side effects. The 'Create' verb is the only behavioral signal.

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 three sentences, starts with the action, and avoids redundancy. The illustrative list of component types and the kind explanation are both useful, with 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?

For a create tool with 6 fully-described parameters and an output schema, the description adequately conveys the entity concept and purpose. It lacks explicit guidance on edge behaviors (duplicate slugs), but that falls under behavioral transparency; the core completeness for selection and invocation is strong. The examples and kind explanation give the agent enough context to know when to use it and what kind to assign.

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 100%, so the baseline is 3. The description's mention that 'The `kind` tag lets you filter later' adds a small behavioral nuance beyond the schema's enum list, but otherwise doesn't elaborate on parameter syntax or constraints already documented in the 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?

The description opens with 'Create a new Component entity' – a specific verb+resource pairing. It then defines what a Component is (subsystem, service, API, database, library, tool), which helps distinguish it from sibling entities like create_task and create_repo, though it doesn't explicitly name those 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?

The description establishes the tool's scope by defining a Component as any coherent unit of functionality and listing concrete examples. This gives an agent clear context for when creating a component is appropriate, but it doesn't explicitly address when to prefer sibling tools (e.g., create_task for tasks).

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?

There are no annotations provided, so the description carries the full burden. It transparently discloses the cascade/dedup behavior and that scaffolded subtopics (overview, rules) are auto-created, which is genuinely useful behavioral context beyond what the schema shows. A minor gap: it doesn't disclose whether creating a governance entity is destructive or idempotent, though the 'Create a new' phrasing implies safe creation.

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 well-structured: a short definition sentence, then supporting context about usage and cascade, then a one-line note on scaffolding. Every sentence earns its place, front-loaded with the core purpose, and free of 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?

The description is thorough for a creation tool: it covers purpose, examples, referral mechanisms, cascade behavior, and scaffolding defaults. With an output schema present, return values need no explanation. It could be more complete if it explained parameter semantics (especially aliases and description), but for a create tool with a clear purpose and rich behavioral context, it is substantially 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?

Schema description coverage is 0%, so the description must compensate. It explains the 'slug' concept implicitly (as the identifier for referencing governance via frontmatter) and the scaffolded subtopics, but it does not explain what 'description' or 'aliases' mean or how they're used. The description mentions aliases implicitly by noting governance can be referenced multiple ways, but doesn't clarify the aliases parameter's purpose or format.

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 creates a 'Governance entity' and defines it as 'a reusable guideline' holding cross-cutting rules. It distinguishes this from sibling tools like create_repo and create_task by naming the specific entity type and enumerating concrete examples (security policies, API design standards, branding guidelines).

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 explicitly explains how governance entities are referenced ('via governance: [...] in frontmatter or via add_governance') and describes the cascade behavior during task pack assembly, including deduplication. This tells the agent when creation matters and how it interacts with other entities, though it doesn't name an exclusion condition — the reference and cascade mechanics serve as strong usage context.

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?

No annotations are provided, so the description carries the full burden. It describes the semantic content of a Repo entity but doesn't disclose behavioral traits like whether creating requires certain permissions, whether duplicates by slug are rejected, whether it's idempotent, or what happens on name conflicts. The aliases 'globally unique' constraint is mentioned in the schema, not the description. This is a mutating create operation with no behavioral disclosure beyond the entity meaning.

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 compact and well-structured: one sentence states the core action, followed by a clarifying paragraph on Repo semantics and the parent-component relationship with a concrete example. It's efficient with no filler, though it could arguably be tighter.

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 an output schema present, return values need not be described. All 5 parameters are documented in the schema (100% coverage). The description covers the entity semantics well. The main gap is the lack of behavioral disclosure for a mutating operation (no annotations), but the schema and output schema provide substantial structure, and the conceptual richness compensates.

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 100%, so the schema fully documents all 5 parameters. The description adds conceptual context about 'slug', 'component' (parent relationship with example), and what a Repo holds, which helps interpret the 'description' parameter's purpose. However, it doesn't detail format constraints beyond what the schema already states. Baseline 3 is appropriate given high schema 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 clearly states the tool creates a new Repo entity and elaborates on what Repos hold (facts about codebase: style, testing, layout, etc.). The parent-component relationship is explained with a concrete example. It's specific enough, though it doesn't explicitly distinguish from sibling tools like create_task or create_governance, though the entity type ('Repo') naturally differentiates.

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 explains what a Repo is and its optional parent-component relationship, which gives useful conceptual context. However, it doesn't state when to use this vs alternatives, nor mention any prerequisites or exclusions. There's no explicit 'use for X, not for Y' 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?

No annotations are provided, so the description carries full disclosure burden. It explains that Tasks are transient and scaffold subtopics (goal, plan, notes), which is useful behavioral context. However, it doesn't disclose what scaffolding actually creates (e.g., do these subtopics auto-appear?), default behaviors, idempotency concerns, or what happens if slug conflicts. The behavioral description is surface-level.

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 three sentences and front-loaded with the core action. Every sentence adds value: the first states purpose, the second explains the entity's nature and linking behavior, the third notes scaffolding. No wasted words, though the second sentence packs a lot of conceptual density.

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?

Has an output schema and 100% param coverage, which lowers the bar. The description explains the entity concept (transient, composed context, scaffolding) which helps agents understand the broader workflow. However, it doesn't clarify the create-vs-scaffold relationship, whether the scaffolded subtopics appear on creation or require separate calls, or how this interacts with the link_task flow beyond mentioning it. Reasonable but with gaps.

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 100%, so the schema thoroughly documents each of the 4 parameters including defaults and formats. The description adds marginal context by noting scaffolds ('goal, plan, notes') which relates to how parameters feed scaffolding, but doesn't add per-parameter meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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 identifies 'Create a new Task entity' with a specific verb+resource. It adds context that Tasks are 'transient units of work' and mentions scaffolding. It distinguishes from siblings like create_repo/create_governance by specifying 'Task entity', though it doesn't explicitly name alternatives. The 'transient' framing distinguishes Tasks from other persistence entities, earning a 4 rather than 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?

The description states Tasks compose context via linking to Component/Repo/Governance refs, which implies when to use it, but doesn't explicitly differentiate from related operations like upsert_context or suggest_task_links. The phrase 'via link_task' hints at follow-up usage but no explicit when/when-not guidance or alternative tool references are given. Adequate but not explicit.

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?

No annotations are provided, so the description carries the full burden. 'Delete' implies destructive behavior, but the description doesn't disclose irreversibility, permanence, whether the operation can be undone, or any side effects. The only behavioral hint is that the parent entity survives. For a destructive mutation tool with zero annotation coverage, more transparency is needed.

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 compact two-sentence fragment that conveys its core purpose efficiently without wasted words. It's appropriately short for a simple single-parameter tool, though it could include slightly more detail without becoming verbose.

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 destructive mutation tool with zero annotations, zero schema coverage, and no parameter documentation, the description is notably thin. While an output schema exists (which helps the agent understand return values), the description fails to address the critical 'ref' parameter semantics or the permanence of deletion. Given the destructive nature and lack of structured support, this should provide more guidance.

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 mentions nothing about the 'ref' parameter - what it references, what format it takes, or how to obtain valid refs. The description names the resource (subtopic) but never connects that to the required 'ref' parameter. The schema only says it's a string, leaving the agent to guess what identifier to supply.

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 'Delete a single subtopic' which is a specific verb (delete) plus resource (subtopic). It additionally clarifies the parent entity is preserved, which adds useful scope nuance. However, it doesn't explicitly differentiate from sibling tools like delete_entity or upsert_context, though the term 'subtopic' provides some distinction.

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 phrase 'Parent entity is preserved' gives some implied usage context, suggesting this is safe for removing sub-elements without affecting parent structures. However, there's no explicit when-to-use vs when-not-to-use guidance, nor any mention of alternatives like delete_entity or upsert_context for removal scenarios.

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?

No annotations are provided, so the description carries full burden. It thoroughly discloses cascade behavior: deletes ALL subtopics, cleans up aliases, task_links, governance links, uses-graph edges, and nullifies repo->component parent pointers. Also explicitly flags it as 'Destructive.' This is exceptional behavioral transparency with no annotation support.

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 concise paragraphs, each serving a clear purpose: what's deleted, what's cleaned up, and the ref requirement. Slightly verbose formatting with line breaks but no wasted words. The information density-to-length ratio is good.

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?

Despite having an output schema, this is a destructive mutation with zero annotations. The description fully covers the scope of destruction, cascade effects, and the required ref type. For a 1-parameter destructive tool, this is complete. It doesn't mention return values but an output schema exists to cover that.

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 has only one parameter (ref) with 0% description coverage in the schema, but the description compensates by specifying it must be an entity-level ref (not a subtopic ref). For a single parameter that's essentially a resource identifier, this level of guidance is sufficient and adds meaning 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?

Description clearly states the verb (delete) and resource (entity), explicitly notes it deletes ALL subtopics, and warns it's destructive. The explicit destructive warning and mention of ALL subtopics distinguishes it from any potentially confusing sibling operations, and no other sibling is a delete 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?

Explicitly states it requires an entity-level ref (no subtopic), which is a clear usage constraint. It doesn't name specific alternative tools, but among siblings there are no obvious race-condition alternatives since delete_context is for a different concept. The dependency constraint (entity-level ref) provides good context.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly states this is a read/get operation returning config data, implying non-destructive behavior. However, it doesn't describe side effects, whether the return includes derived/aggregated data, or any caching behavior. Moderate 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?

A single, focused sentence that states the purpose and the returned fields with zero wasted words. Front-loaded with the verb and resource, and the parenthetical list is compact and informative.

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 is a simple zero-parameter read operation with an output schema present, so the description need not explain return values (the output schema covers that). Combined with listed fields, the description is adequate and complete for its simple scope.

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 with 100% schema coverage (a vacant properties object is fully covered). Per the rubric, 0 params earns a baseline of 4. The description appropriately names the exact fields returned, which adds meaningful context about what the empty parameter set will fetch.

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+resource ('Return the current ContextForge config') and enumerates exactly what fields are returned ('always_include, workspaces'). It clearly distinguishes from siblings like get_context or get_current_workspace by specifying this is the full config.

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 clearly states what it returns, making it obvious to use when you need the config overview. However, it doesn't explicitly mention when NOT to use it or reference alternatives such as get_current_workspace for workspace-only needs. No exclusion or alternative guidance is provided.

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?

No annotations provided, so the description carries the burden. It discloses return shape ('meta + all subtopics' for entity refs) which is useful behavioral context. However, it doesn't disclose what happens for invalid refs, error behavior, or whether this is a safe/read-only operation — though 'read' implies non-mutation. Lacks depth but not contradictory.

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?

Description is compact (two short paragraphs) and front-loaded with the main purpose. Every sentence earns its place: purpose, ref types, examples, and return behavior. Slightly repetitive between 'Read the current context' and the ref explanation, but overall 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?

Has an output schema, so return values aren't the description's job. For a 1-param read tool, the description covers purpose, ref formats, and per-ref-type behavior. Could mention error handling or default behavior for empty/invalid refs, but for a simple read tool this 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?

Schema coverage is 0%, so the description must compensate. It does explain the ref format with concrete examples ('component:api-gateway' and 'component:api-gateway/auth'), which adds meaning beyond the bare schema. However, it doesn't detail the format rules of refs (required structure, valid prefixes) beyond two examples. With only 1 required parameter and 0% coverage, this is acceptable but not thorough.

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?

Clear verb+resource: 'Read the current context for an entity or a single subtopic.' Distinguishes ref types (entity vs subtopic) and states what's returned for each. However, it doesn't explicitly distinguish from sibling tools like get_config, though the read-context purpose is clear enough.

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?

Description explains when to use it (reading context for entity/subtopic) and shows ref format examples. But it doesn't explicitly say when NOT to use it or name alternatives (e.g., when to use search vs get_context, or upsert_context for writing). The ref types are explained but no exclusions are given.

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?

No annotations are provided, so the description carries the burden. The description clarifies a behavioral detail: that the MCP client supplies the path from its Roots and that ContextForge doesn't read Roots directly in v0. This adds useful context. However, it doesn't disclose what happens if the path has no bound repo or component (e.g., error vs null result) 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?

A single, focused sentence in the description plus detailed parameter documentation in the schema. Zero waste, front-loaded with the core purpose. This is appropriately concise.

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 an output schema present, return values are handled structurally. The tool is a simple single-parameter resolution operation. The description covers the core purpose and even adds an implementation detail (Roots handling in v0). However, it doesn't address edge cases like unbound paths, which an agent might benefit from knowing, and given no annotations, the safety profile (read-only vs mutating) is unstated.

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 100%, so the schema documents the single path parameter fully, including the note that the MCP client supplies it from Roots. The description adds the meaning that path resolves to a repo/component binding, which marginally extends the schema's description. Baseline 3 is appropriate since the schema handles the parameter 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 action (resolve a workspace path) and resource (its bound repo and parent component). It's clear what the tool does. However, it doesn't distinguish itself from siblings like resolve_ref or bind_workspace/unbind_workspace, though its verb and resource are distinct enough.

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 vs alternatives. It doesn't mention when you'd need to resolve a workspace path, or contrast with resolve_ref, or explain why one would use this rather than looking up a repo directly. The 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.

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

This is a sophisticated tool with meaningful behavioral nuance: default parameters (include_always=True, focus=True), dropping of overflow subtopics into a `dropped` field for on-demand pull, and the specific bypass rule for subtopic-level refs. The description transparently documents all this behavior beyond what the schema annotations (none provided) could convey. No annotation contradictions.

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 dense but well-structured: a one-line purpose, then three paragraphs covering returns, focus behavior, and bypass rules. It's front-loaded with the core purpose in the first line, and the paragraphs build logically. Slightly longer than necessary but every sentence contributes meaningful behavioral 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?

For a 5-parameter tool with 100% schema coverage and an output schema, the description is remarkably complete. It explains the return structure (meta+subtopics, linked refs, governance), the focus/dropping mechanism, the always_include merge, and the bypass rule — covering all the non-obvious behaviors an agent would need to correctly invoke and interpret results.

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 100%, so the baseline is 3. The description adds meaning above this: it connects include_always to config.json's always_include, explains that focus=True triggers FTS-narrowing and that per_entity_top_k controls max subtopics per narrowed entity, and explains dropped refs relate to per_entity_top_k overflow. This adds semantic context beyond the schema's terse parameter descriptions, though min_score (bm25 relevance floor) is only partly elaborated.

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 ('Assemble the full context pack for a task') and then details exactly what it returns (task meta+subtopics, resolved linked refs, deduplicated governance). This clearly distinguishes it from siblings like get_context or get_config, establishing a distinct retrieval role.

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 clearly explains when focus mode is used ('entity-level refs with more than per_entity_top_k subtopics are FTS-narrowed') and when subtopic-level refs bypass narrowing. It explains what focus does (narrowing vs returning dropped refs). However, it doesn't explicitly say 'use X instead when...' to name alternatives among the 33 siblings, though the dropped-refs path mentions get_subtopic/get_context as follow-up tools.

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?

No annotations are provided, so the description carries the burden. It discloses the side effect of storing content with source tracking and notes that source_fetched_at is auto-set, which is useful. However, it doesn't describe what happens on overwrite of an existing ref, whether this mutates or supplements existing snapshots, or the return shape.

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 tight — three short sentences with no waste. The usage guidance is front-loaded in the first sentence, and the technical cue (source_fetched_at auto-set) earns its place as it informs agent expectations. Slightly verbose 'then ContextForge owns it as a snapshot' but acceptable.

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 is a write/import with 4 parameters (100% schema coverage) and an output schema present. The description covers the core workflow (post-fetch import), source tracking, and a key side-effect (source_fetched_at auto-set). Remaining gaps like overwrite behavior are minor for a well-documented schema with output schema.

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 100%, so baseline is 3. The description adds meaning to source_url ('canonical') and source_name (gives example values 'confluence', 'notion', 'github-wiki'), and explains the source_fetched_at auto-fill behavior tying into the schema semantics.

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+resource ('Store content fetched from an external source as a subtopic') and clearly connects it to the sibling tools for Confluence fetching. It distinguishes itself from append_context/upsert_context by framing itself as the snapshot-owner for external fetches with source tracking.

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 explicitly states when to use it: 'after another MCP tool returns page content', naming an example (Atlassian MCP for Confluence). It implies ContextForge then owns the snapshot, distinguishing from alternative write tools, though it doesn't explicitly name alternatives or exclusions.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose the cascade behavior for governance refs ('cascade to the assembled pack','cascades automatically too'), which is genuinely useful behavioral context. However, it doesn't mention whether the operation is idempotent, whether it overwrites existing refs, or what happens to previously-linked refs. With zero annotations, more behavioral detail would be beneficial.

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 compact and front-loaded with the core action in the first sentence. The second paragraph adds valuable explanatory context without unnecessary padding. Efficient and well-organized, though the cascade explanation could arguably be tightened further.

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 only 2 flat parameters and no enums, so complexity is moderate. An output schema exists, which relieves the need to document return values. The description covers the core purpose and the cascade side-effect, but gaps remain around ref string format, idempotency, and error conditions which matter for a wiring operation. Adequate but not fully 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?

Schema description coverage is 0%, so the description must compensate, but it does so weakly. It mentions 'refs' can be component/repo/governance types and optionally include subtopic, and clarifies task_slug refers to a task. However, it doesn't specify the format of refs strings (e.g., 'component:slug:subtopic'), whether task_slug must be exact or accepts aliases, or what happens if a task doesn't exist.

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 ('Wire') and identifies the resource (refs of component/repo/governance, optionally with subtopic) being attached to a task. It distinguishes clearly from siblings like unlink_task or add_governance by stating the action of linking refs to a task. However, it could be more explicit about the exact modification being performed (adds refs to an existing task).

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 useful context about when subtopic-level refs are preferred ('keep packs focused') and explains governance cascade behavior. However, it doesn't explicitly contrast with alternatives like add_external_ref (external vs internal refs) or suggest_task_links (suggestion vs direct wiring), nor does it state when one should NOT use this tool.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. Being a 'list' operation implies read-only behavior, but there's no description of pagination, return format, or whether the output is exhaustive. The description adds minimal behavioral context beyond the verb itself.

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?

Extremely concise single sentence with zero waste. It states the action, the resource, and the optional filter in one clear sentence.

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 an output schema that explains return values, and the input is a single well-documented optional parameter with 100% coverage. For a simple filtered-list tool, the description is nearly sufficient, but it lacks behavioral details like pagination or ordering that would round out completeness for a list operation.

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 100% and the kind parameter is well-documented with the allowed enum values listed in the schema itself. The description adds the 'optional' clarifying note in prose ('optionally filtered'), reinforcing what the schema already states via default: null.

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?

Clear verb+resource: 'List all Components, optionally filtered by kind.' It states the resource (Components) and the optional filtering capability. It doesn't explicitly differentiate from sibling list tools, but the name and scope are reasonably self-evident.

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 when-to-use guidance is provided. The description implies list-related usage but doesn't state when to prefer this over alternative listing tools like list_repos, list_tasks, or list_governance_entities. No exclusions or alternatives named.

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?

No annotations are provided, so the description should carry the full burden of behavioral disclosure. 'List' does imply a read-only operation, which is the primary behavioral trait, but the description doesn't disclose output format, pagination behavior, ordering, or whether empty results or errors are possible. For a simple list operation with no parameters, the minimal disclosure is somewhat acceptable but still thin.

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, efficient sentence with zero waste. However, it is arguably under-specified rather than concise in a useful way — it states only the bare minimum without any clarifying context, so it doesn't earn a 5.

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 (0 params, complexity is low), the description is simple. It has an output schema present, which reduces the need to document return values. However, given the large sibling set including multiple list tools and governance-related tools, the description falls short on differentiating scope. It also lacks guidance that could help an agent decide when 'governance entities' is the right resource to list.

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 and schema description coverage is 100% (trivially, since the schema is empty). With no parameters to describe, the parameter dimension is essentially satisfied by the empty schema. The description adds no parameter information, but none 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 'List all Governance entities' uses a clear verb (list) and resource (Governance entities), but does not distinguish it from the many sibling tools. It is a minimal, clear statement but provides no differentiation from related list tools like list_components, list_repos, or list_tasks, nor from the adjacent create_governance and add_governance tools.

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. With 33 sibling tools including multiple 'list_' and governance-related tools, the description provides no context about what distinguishes 'Governance entities' from other entity types or when listing governance is appropriate versus searching or resolving references.

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?

No annotations are provided, but this is a read-only list operation which the description's 'List' verb conveys clearly. It's unambiguous as a read operation given the verb choice. However, it doesn't disclose return format, ordering, pagination, or whether it includes all metadata or just summaries. The verb carries most of the transparency burden adequately.

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 words, zero waste. Every word earns its place: 'List' states the action, 'all' states the scope, 'Repos' states the resource. This is the ideal conciseness for a trivial list operation.

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 zero parameters, an output schema exists, and this is a simple list operation, the description is nearly complete. However, it doesn't specify what the returned list contains (e.g., repo names only vs. full repo objects) or whether there are limits on the result set. For a simple list tool with an output schema present, this is adequate but could mention the scope of the listing more fully.

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?

There are zero parameters, so parameter semantics are not applicable in a detailed sense. The description's mention of 'all' signals the complete scope with no filtering options, which is all the agent needs to know given no parameters exist. Baseline 4 is appropriate for a 0-param tool.

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 'List all Repos' clearly states the verb (List) and resource (Repos), specifying the full scope of the operation. It's terse but unambiguous. However, it doesn't differentiate from sibling list tools like list_tasks, list_components, and list_governance_entities, though the resource name distinguishes it.

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. Sibling tools include list_tasks, list_components, and list_governance_entities, and the description doesn't clarify when listing repos is appropriate or what distinguishes it. No exclusions or context provided.

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?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It's a read/list operation (implied by 'List'), but there's no mention of what happens with stale sources—whether they're just listed or also returned with their fetched status, what the response shape is, or any pagination/limits. The description doesn't specify return behavior beyond listing.

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, efficient sentence that front-loads the core action and resource. No wasted words, and it directly communicates the tool's purpose without padding.

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 a simple single-parameter signature with a 100%-covered schema and an output schema provided. However, for a list tool that likely feeds into refresh_source or import workflows, the description doesn't clarify how these stale sources relate to sibling tools like refresh_source, nor what the returned entities contain beyond being 'imported subtopics'. It's minimally adequate but leaves the workflow context implicit.

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 100%, meaning the parameter older_than_iso is fully documented in the schema with a clear description and example format. The description itself mirrors the schema's cutoff semantics but doesn't add new meaning beyond what the schema already provides. Baseline 3 is appropriate.

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 action ('List') and the resource ('imported subtopics'), with a specific filtering criteria ('source_fetched_at older than a cutoff'). It's specific enough to identify the tool's core function, though it doesn't explicitly distinguish from siblings like list_components or list_repos beyond naming the specific resource type 'imported subtopics'.

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 when-to-use guidance is provided. The description doesn't mention when the agent should choose this tool over alternatives like list_components, list_repos, or list_tasks, nor does it state what the tool is NOT for. There's no context about prerequisites or typical workflows.

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?

No annotations are provided, so the description carries the burden. Since this is a 'List' operation with zero parameters, it implies a read-only behavior which is self-evident from the purpose. However, it doesn't disclose what 'all' means (scope: all in current workspace? all across workspaces?), pagination behavior, or output volume expectations. For no annotations, 'List all' is minimally transparent but lacks scope detail.

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 ('List all Tasks.'), consisting of exactly one sentence with zero wasted words. It's appropriately sized for a simple list operation with no parameters. Not verbose at all, though arguably too terse.

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?

There is an output schema present, so the return format is presumably documented there. The tool is simple (0 params, list operation). However, given the many sibling tools and existence of get_task_pack, link_task, suggest_task_links etc., the description could benefit from clarifying the scope of 'all tasks' (pagination, filter, workspace scope) and what relationship this bears to get_task_pack.

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, and schema description coverage is 100% (trivially, since there are no properties). The description doesn't need to elaborate on parameters that don't exist. The baseline of 4 for 0 params applies here.

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 'List all Tasks' which clearly identifies the verb (List) and resource (Tasks). It's adequate but minimal. It does not distinguish from siblings like list_components, list_repos, list_governance_entities beyond the resource name, though the verb+resource combination makes it reasonably clear what the tool does.

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. With many sibling tools (list_components, list_repos, list_governance_entities, get_task_pack, link_task), the description gives no context about when listing all tasks is appropriate vs. using get_task_pack or other task-specific tools. No exclusion criteria or usage context provided.

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?

No annotations are provided, so the description carries the burden. It does disclose a key behavioral trait: the tool only returns the URL and does NOT perform fetching ('ContextForge does NOT fetch'). However, it does not describe return format, error behavior, or whether the ref needs to correspond to an existing subtopic, which would be useful given the absence of annotations.

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 efficient and well-structured, with the core sentence first followed by a helpful clarifying note about ContextForge's non-fetching behavior. Every sentence earns its place; there is zero waste.

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 a single param, an output schema, and clear sibling context (import_content is the companion). The description explains the workflow (refresh → fetch externally → import_content) and the tool's limitation. It's reasonably complete for a simple one-param tool, though it could explain the relationship between the input ref and the returned url in more detail.

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?

With only 1 parameter and 0% schema description coverage, the description must compensate. It mentions 'ref' in passing ('import_content again with the same ref') and implies the ref identifies the subtopic. However, it doesn't explicitly explain what format the ref should take or how it relates to the returned source_url. With only one param, this is a modest gap but the description provides partial 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 clearly states the tool returns the source_url for a subtopic so the caller can re-fetch. The verb ('Return') and resource ('source_url for a subtopic') are specific. It could be slightly clearer about what 'subtopic' and 'ref' mean in the ContextForge context, but relative to siblings (import_content, get_context), it's fairly distinguishable.

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 explicitly states when to use this tool: when the caller needs to re-fetch fresh content. It also explains what NOT to do — 'ContextForge does NOT fetch' — and directs the caller to use another MCP tool or HTTP fetcher, then call import_content again with the same ref. This is excellent guidance that prevents misuse.

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?

No annotations are provided, so the description carries the full burden. It discloses that this is a rebuild operation and that the filesystem is the source of truth, implying it overwrites existing index state. However, it doesn't state side effects beyond rebuilding (e.g., whether the operation blocks, is destructive to unlinked context, or the expected duration/cost). With zero annotations, a 3 is reasonable — some transparency added but not deep.

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 tight sentences with zero wasted words. The intent, the trigger conditions, and the data-model principle are all conveyed efficiently. Front-loaded with the core action first.

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 zero-parameter tool with an output schema, the description covers the essential information: what it does, when to run it, and the source-of-truth model. It doesn't elaborate on expected return/output, but an output schema exists to carry that burden. Slightly more detail on cost/impact could push this to 5, but it's largely 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?

There are 0 parameters and schema description coverage is 100% (nothing to document). The baseline for zero-param tools is 4. The description adds value by explaining what the operation accomplishes (rebuild from markdown), even though there are no parameters requiring elaboration.

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?

Description states a specific verb+resource: 'Rebuild the SQLite + FTS5 index from markdown files on disk.' This clearly distinguishes from siblings — notably from refresh_source and search — by identifying the full-reindex operation on the index built from markdown files. It names both the technology involved (SQLite + FTS5) and the source of truth (filesystem).

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?

Provides explicit when-to-use guidance: 'Use after manual edits on disk, or if the index seems stale.' It also clarifies the underlying model ('Filesystem is the source of truth'), implicitly warning against expecting the index itself to be authoritative. This distinguishes it from refresh_source (likely incremental) as the heavier, manual-fallback reindex.

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?

No annotations are provided, so the description carries full burden of behavioral disclosure. The description states only that it removes an alias, but doesn't reveal whether it's destructive/irreversible, whether removing fails silently for non-existent aliases, whether errors surface, or whether it triggers cascade effects elsewhere in the system. For a mutation operation with zero annotation coverage, this is a notable 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?

Single concise sentence with zero waste. It's efficient and front-loaded. However, it errs on the side of under-specification rather than genuine conciseness; the terseness is partly a symptom of lack of behavioral detail rather than purposeful compression.

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?

There is an output schema, so return-value documentation isn't required. However, this is a mutation tool with no annotations, 0% schema description coverage, and a minimal one-sentence description. Given the complexity of distinguishing behavior around aliases (validation, error handling, idempotency) and the sibling add_alias/remove_alias pair, the description should do more to explain the operation.

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 parameter documentation. Neither 'ref' (presumably an entity reference) nor 'alias' (the alias string to remove) is explained in the description. The names are reasonably self-explanatory, but given zero parameter coverage in the schema descriptions, the tool text adds no semantic value beyond the parameter names themselves.

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 'Remove an alias from an entity' with a clear verb-action (remove) and resource (alias on an entity). It pairs well with the sibling add_alias tool, and while it doesn't explicitly differentiate, the inverse operation is obvious. Purpose is clear though minimal.

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 vs alternatives. It doesn't explain prerequisites (e.g., must the alias exist? must the entity exist?), nor does it mention any relationship to add_alias, resolve_ref, or other alias-related tools. No exclusions or context provided.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states the action without mentioning whether removal is idempotent, what happens if the ref doesn't exist, whether the always_include list is consulted automatically, or what state changes occur. For a mutation operation with zero annotation coverage, 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?

One concise sentence with no wasted words. However, it is under-specified rather than efficiently concise—the brevity comes at the cost of missing behavioral and usage information.

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?

Despite having only 1 parameter and an output schema, the description is thin for a mutation tool with no annotations. There's no mention of error behaviors (missing ref, already-absent ref), no note about the relationship to the current workspace or config, and no context about why a ref would be in always_include in the first place. Sibling tools like add_always_include suggest a paired operation, but this isn't explained.

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 'ref' parameter. The description mentions 'a ref' but doesn't clarify what format refs take (resolvable vs literal), whether the ref must be currently present in the list, or how it relates to the resolve_ref sibling tool. The schema only says it's a string, which is minimally informative.

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?

Description states the verb ('Remove') and resource ('a ref from the always_include list'), which clearly identifies the action. It's specific enough to be understood on its own, though it doesn't add much detail beyond the tool name itself. It's distinguishable from siblings like add_always_include and remove_external_ref.

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 alternatives. The sibling tools include add_always_include, remove_external_ref, and others, but the description provides no context about when removing from always_include is appropriate versus other removal operations, nor any prerequisites or side effects to be aware of.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states the action ('detach') with no information about side effects, whether this is destructive/irreversible, whether it affects task links or context, or what the response contains. For a mutation tool with zero annotation coverage, this is insufficient behavioral disclosure.

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 single-sentence description is extremely concise with no wasted words, which is positive. However, it leans toward under-specification rather than genuine conciseness—one sentence with no parameter detail or usage context is minimal rather than efficient. It's acceptable but not well-structured for helping an agent decide on invocation.

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?

Despite having an output schema (which relieves the description of explaining return values), the description is incomplete for a mutation tool. With 3 required parameters at 0% coverage, no annotations, and 38 siblings to distinguish from, the description fails to provide enough context about what the tool does in detail, what prerequisites exist, or how it relates to add_external_ref and resolve_ref.

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 information about any of the three parameters (task_slug, system, id). The parameter names give some hints—task_slug likely identifies the task, system the reference source, and id the reference identifier—but the description provides zero elaboration on their semantics, required formats, or relationships.

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 'Detach an external reference from a task' uses a clear verb (detach) and resource (external reference from a task). It's a short, single sentence that states the core operation, but it doesn't elaborate on what an external reference is or distinguish it from related operations like resolve_ref or add_external_ref beyond the obvious inverse relationship.

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 vs alternatives. The sibling list includes add_external_ref (the natural inverse) and resolve_ref, but the description doesn't mention these alternatives or provide any context about prerequisites, such as whether a reference must exist or what happens to linked data. With 38 siblings, the absence of differentiation is a notable gap.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states what the tool does but does not disclose side effects, whether this is destructive, whether it affects related entities, error conditions, or what the return value looks like. Output schema exists but the description doesn't explain behavioral implications of detaching governance.

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 efficient sentence with zero wasted words. It is appropriately concise, though it borders on under-specification rather than achieving economy through completeness.

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?

This is a mutation tool (detaching governance) with no annotations, no parameter descriptions, and 0% schema coverage. The presence of an output schema helps, but the description does not explain detach semantics, reversibility, or what happens to the entity afterward. For a two-parameter mutation tool with zero schema coverage, significantly more should be provided.

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 parameters (ref, governance_ref) have no descriptions or enums, so the description must compensate. However, the description only identifies governance_ref as the thing being detached and ref as the entity, which it does implicitly but not explicitly. The parameter semantics are not expanded—no clarification of what format ref and governance_ref take.

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 'Detach a governance ref from an entity' uses a specific verb (detach) and clearly identifies the resource (governance ref) and target (entity). It is somewhat terse but clearly distinguishes from sibling 'add_governance' which attaches. It could be clearer about what 'governance ref' means, but it communicates the core 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?

There is no guidance on when to use this tool versus alternatives. No mention of prerequisites (e.g., the ref must currently be attached), no mention of the inverse operation add_governance, and no conditions under which detaching might fail or be inappropriate. Zero usage context provided.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the search strategy (exact slug, exact alias, case-insensitive name substring) and the return format (ranked candidates with ref/source/score). However, it doesn't describe things like max candidate count, failure behavior, or whether this performs any side effects — though the read-only nature is strongly implied (it returns candidates, doesn't write).

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 compact and front-loaded. The first line states the core purpose with illustrative examples. The second paragraph adds search strategy and return format in a single dense sentence. No wasted words or tautological phrasing.

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 output schema exists, so return-value details are partially covered. Given the tool's moderate complexity (fuzzy matching with ranking), the description covers the resolution logic, output structure, and use case. It doesn't explain edge cases (e.g., empty results, tie-handling), but for a resolution/query tool this is adequate completeness.

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 100%, so both parameters are documented in the schema. The description adds value by explaining the query semantics (fuzzy/nickname-based) and type_filter usage ('restrict to component|repo|task|governance'). The examples given ('the gateway', 'gw', 'auth-gw') add significant meaning beyond the schema's generic 'free text' description.

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 purpose: resolving fuzzy queries ('the gateway', 'gw', 'auth-gw') to candidate refs. It clearly names the resource type (refs) and the action mechanism (exact slug, alias, case-insensitive substring matching). It distinguishes from siblings by indicating it's a pre-write resolution step, not a list or CRUD 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?

The description gives concrete guidance: 'call this before writing if the user refers to something by nickname or description.' This establishes the when-to-use context. It doesn't explicitly list alternative tools or when NOT to use it, but the instruction to call before writing is clear enough given the sibling set context.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It identifies FTS5 as the engine and notes phrase treatment, but does not disclose return format (though output schema exists), ranking behavior, or limitations beyond operator unsupported. For a search tool, notably absent is any note about how results are scored/ordered or whether the search is subject to current workspace context.

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, and it's front-loaded with the key purpose. It's efficiently written with no wasted words, though it could add a small amount of usage context without harming conciseness.

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 is moderately complex with 3 paramters (1 required) and an output schema. The schema fully documents all parameters, and the output schema presumably covers return structure. However, with no annotations and a brief description, context around search semantics (ranking, scope across workspaces, how entity_type interacts with subtopic content) is thin, leaving residual ambiguity for agent selection.

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 100%, with clear descriptions for query (free text, phrase, no operators), limit (max results, default 20), and entity_type (optional filter with allowed values). Since the schema fully documents each parameter, the baseline of 3 is appropriate; the description adds no additional parameter semantics beyond what the schema already provides.

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 'Full-text search (SQLite FTS5) across all subtopic content' identifies the tool as a search over subtopic content using FTS5. It's reasonably specific about the mechanism (full-text search) and scope (all subtopic content), but it does not explicitly distinguish it from sibling search-like operations such as resolve_ref or list_* tools, and the description is somewhat brief about what constitutes 'subtopic content'.

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 implies the tool is for free-text searching of content across subtopics, and the query parameter note ('treated as a phrase, operators not supported') provides useful usage guidance. However, there are no explicit when-to-use or when-not-to-use instructions vs siblings like resolve_ref, get_context, or the list_* tools, leaving the agent to infer appropriate usage context.

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 provided, the description carries the full burden. It discloses the traversal mechanism (walks uses graph from anchors or existing links), the scoring approach (FTS against task description + notes), and the exclusion behavior (excludes already-linked refs). The configurable depth/top_k behavior is documented. Missing are return format details and whether this is read-only (implied 'propose' but not explicit), which with an output schema somewhat mitigates this.

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?

Two densely informative paragraphs with zero waste. The first sentence states the purpose, the second paragraph walks through the algorithm in a single efficient run-on that conveys the full pipeline. Every sentence earns its place, 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?

The tool has moderate complexity (graph traversal, FTS scoring, multiple configurable params) and an output schema exists, relieving the description of return-value burden. The description covers the what/why/algorithm and key exclusions. Minor gap: no explicit statement of read-only behavior or expected performance/limitations, but given the output schema and thorough algorithm description, it's largely 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?

Schema description coverage is 100%, so the schema documents all four parameters clearly (depth default 3, top_k default 10, anchors optional list falling back to existing links, task_slug required). The description adds context on how anchors interact with the traversal (None falls back to existing links) which the schema implies. Since the schema covers everything, baseline 3 is appropriate.

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 ('Propose candidate refs to link into a task') and resource, and immediately distinguishes from siblings like link_task and unlink_task by being a suggestion/recommendation tool rather than an actual mutation. The multi-step algorithm (walk uses graph, collect components, FTS-score, return top-K) gives a precise picture of the tool's 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 clearly explains when to use it (proposing candidate refs/link suggestions) and gives the mechanics across paragraphs. It doesn't explicitly name alternative tools or state when NOT to use it, but the distinction from link_task/unlink_task (which mutate links directly) is implicitly clear. A named alternative would push this to 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?

No annotations were provided, so the description carries the full burden. It discloses the log location (~/.contextforge/logs/contextforge.log), that it's rotating, and enumerates the log content types. However, it doesn't mention that this is a read-only/non-destructive operation explicitly, nor does it describe the output format or what a tail operation entails beyond returning lines. Decent coverage but could add that it's a safe read in a persistent location.

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 two paragraphs, front-loaded with the core action in the first sentence, then enriched with valuable context about log location, rotating nature, and content types. Every sentence adds value — the log path is actionable, the rotating note explains why the tail is bounded, and the content enumeration tells the agent what signals it can extract. 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?

For a simple read operation with one well-documented parameter and an output schema present, the description is quite complete. It covers the log location, rotation behavior, content types, and the diagnostic purpose. The only gap is not stating the return format explicitly, but the presence of an output schema helps offset that. This is a strong, self-sufficient description 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 coverage is 100%, and the single parameter (n, default 50) is well-documented in the schema itself with 'number of lines to return (default 50).' The description doesn't add much beyond what the schema already states about the parameter, so baseline 3 is appropriate. No parameter-specific enrichment in the description is needed given full schema 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 clearly states the verb (tail/return most recent lines) and the resource (persistent usage/debug log), and even details what log entries capture (tool invocations, pack assemblies, etc.). It also explains WHY the log matters (primary signal for tuning focus/governance behavior), which distinguishes it from the write-oriented sibling tools like append_context or upsert_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 explains that this is the primary diagnostic signal for understanding real usage and tuning focus/governance behavior, giving clear context for when to use it. It doesn't explicitly name alternatives to exclude, but the purpose is distinct enough among siblings (most siblings are write operations, search, or entity management, whereas this is a read/diagnostic tool). Missing an explicit 'use X instead when...' but context is clear.

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?

No annotations are provided, so the description carries the full behavioral burden. The description implies a mutating/destructive action by 'Remove', but it doesn't disclose side effects—what happens to bound tasks, contexts, or governance entities when the binding is removed. It also doesn't clarify whether the operation is reversible or requires permissions. Beyond the obvious mutation, there's limited disclosure.

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, efficient sentence with zero wasted words. It's appropriately sized for a simple operation with a single parameter. No redundancy or unnecessary elaboration.

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 destructive/unbinding operation, the description is minimal. Even with an output schema present, this tool removes a binding that could have downstream effects on other entities (contexts, tasks, governance). The description should clarify what happens to associated data and how 'path' is used. It's adequate for a 'minimum viable' tool but leaves meaningful gaps for an agent deciding whether unbinding is the right action.

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 single parameter 'path' has 0% schema description coverage, and the description doesn't explain what 'path' refers to—a workspace path? a repo path? something else? The description adds no meaning beyond the schema field. However, with only one parameter, the penalty is modest, and the tool name provides some context. Baseline 3 is appropriate given the single-param nature but the description fails to clarify what path denotes.

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 'Remove a workspace→repo binding.' uses a specific verb ('Remove') and identifies the resource (workspace→repo binding). It clearly states the action. It does provide some sibling differentiation since there's a 'bind_workspace' sibling, making the pairing intuitive. However, it lacks detail on what 'workspace' and 'repo' concepts are.

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 unbind vs remove_governance or delete_entity. It doesn't state prerequisites (e.g., must be bound first) or mention that 'bind_workspace' is the complementary sibling. There is no context about whether this affects tasks, contexts, or other entities linked to the workspace.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only notes idempotency, but doesn't disclose whether the operation is destructive beyond removing links (e.g., does it cascade to delete linked entities?), whether it requires specific permissions, or how it handles refs not currently in the list. The 'Idempotent' statement is useful but thin 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 efficient sentence plus a one-word note. Zero filler words, front-loaded with the action 'Remove refs from a task's link list'. The 'Idempotent' note is a compact but valuable addition. Appropriate length for a simple 2-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?

With only 2 simple parameters, an output schema present, and no nested objects, the complexity is low. However, the description is also sparse: it doesn't clarify what 'refs' are in this system context, and given zero annotation coverage, a bit more detail on behavior would help. The sibling tool naming suggests a link/unlink pair, which provides useful context, but the description itself is minimal.

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%, meaning the schema provides no descriptions for either parameter. The description mentions 'refs' and 'task' in context, mapping loosely to task_slug and refs, but doesn't explain what constitutes a valid ref, the ref format, or constraints on the task_slug. The description adds minimal meaning beyond the parameter names in the 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?

The description 'Remove refs from a task's link list' uses a clear verb (Remove) with a specific resource (task's link list) and subject (refs). It distinguishes from the sibling link_task, which is the inverse operation. However, it doesn't fully describe what a 'ref' is or what the link list represents, leaving some ambiguity about the domain model.

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 inverse operation is implicitly clear given the sibling 'link_task', establishing a paired-use context. However, there's no explicit instruction on when to use this vs alternatives, no mention of when unlinking is appropriate, and no exclusions or caveats beyond idempotency. The 'Idempotent' note gives some safety guidance but doesn't specify effects on already-unlinked refs.

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?

No annotations are present, so the description carries the burden of behavioral disclosure. It discloses a meaningful side effect: 'Clears any previously stored source_url/source_name when content is overwritten without source metadata.' This is genuinely valuable behavioral transparency. However, it doesn't describe what happens on failure (e.g., if parent doesn't exist), return format, or whether overwrite is atomic. Decent transparency but incomplete for a mutation 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 compact and front-loaded with the core purpose in the first sentence. The additional behavioral note about source metadata clearing is worth the space. The blockquote formatting of the warning adds structure. No wasted verbiage, though the line breaks are stylistic.

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 no annotations and an output schema present but 0% parameter coverage, the description is notable for disclosing the source_url/source_name clearing side effect. However, it's short on several fronts: no mention of what happens when ref doesn't resolve or parent doesn't exist (error behavior), no format guidance for ref, and no distinction between create vs overwrite semantics beyond the opening verb. For a data-mutating upsert operation touching a complex content hierarchy, this is incomplete.

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 'ref' implicitly as 'a subtopic ref' and mentions 'content' as the subtopic's full content. However, it doesn't clarify the ref format (how to reference a subtopic), whether content has constraints (length, format), or what 'subtopic' means in the broader data model. With 2 parameters at 0% coverage, the description provides only minimal compensation—the match on the ref meaning is the most useful addition.

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 'Create or overwrite a subtopic's full content' with a specific verb (upsert) and resource (subtopic content). It distinguishes itself from append_context (the sibling would be for adding to existing content rather than overwriting it), though it doesn't explicitly name that sibling. Clear purpose overall.

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 notes 'Requires a subtopic ref' and 'Parent entity must already exist', giving some prerequisite context. However, it doesn't explicitly explain when to prefer this over append_context or how it differs from alternative write operations. Usage context is implied rather than explicitly stated with exclusions or alternative recommendations.

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