coding-os

by kouroshez

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.3.21
Disambiguation3/5
Most tools are domain-clustered with clear purposes, but several clusters overlap: cos_graph_query/search/resolve all find symbols, cos_task_move/reposition both change task status, and cos_dispatch_formula/run/parallel_run are easily confused. Descriptions help, but boundaries are fuzzy in a few places.
Naming Consistency4/5
The dominant pattern is cos_<domain>_<action> (e.g., cos_task_create, cos_graph_query, cos_metric_record), which is predictable. Minor deviations exist: bare names like cos_health, cos_search, cos_details, cos_timeline, cos_promote, and cos_discovery break the pattern without domain prefixes.
Tool Count1/5
86 tools is an extreme count for a single MCP server, far beyond the 'well-scoped' range. Even for a broad 'coding OS' concept, this is excessive and likely to overwhelm agents, increase selection latency, and dilute the value of each tool.
Completeness4/5
The surface is remarkably comprehensive: task lifecycle, metrics, learning, graph analysis, retrieval, docs, and supervision are all covered with no obvious dead ends. Minor gaps exist (no explicit delete for tasks/patterns/observations, some tools are stubs or decision-only), but they are workaround-able and the domain is thoroughly addressed.
Average 4/5 across 86 of 86 tools scored. Lowest: 1.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1850 commits in the last 12 weeks
- Last stable release on August 23, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read behavior is known. The description adds one useful behavioral detail: the response key is `processes` rather than `communities`. However, it doesn't disclose other behavior such as pagination, sorting, or limits beyond the default parameter values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than efficient structure. The phrase 'Louvain process clusters' is cryptic and reads like a fragment, not a clear explanatory sentence. It lacks a proper subject-verb-object structure and doesn't front-load the key information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters with no descriptions and no stated return shape beyond one key, the description is grossly incomplete. It fails to explain the purpose, the meaning of parameters, or the overall response structure. Even with an output schema present, the description adds almost no context for an agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
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 lack of parameter documentation. It doesn't mention any of the three parameters (top, min_size, max_members), their meanings, or how they affect results. The agent is left guessing from parameter names only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Louvain process clusters' is a noun phrase with no verb, making it unclear whether the tool computes clusters, returns clusters, or does something else. It vaguely gestures at community detection via Louvain but doesn't clearly state the action or resource. It also doesn't distinguish this from sibling graph tools like cos_graph_centrality or cos_graph_ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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 context is provided about typical use cases, prerequisites, or conditions under which this tool is preferred. The only hint is about the response key, which is operational, not about usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already providing readOnlyHint=false and destructiveHint=false, the description adds no operational context such as file modification, idempotency implications, or failure modes. The sentence contains no information about side effects or prerequisites beyond the act of recording.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only one sentence long, so it is concise, but it is under-specified rather than efficiently informative. 'Explicitly' adds little semantic value and the sentence does not earn its place by conveying necessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and an output schema, this description is wholly inadequate. It does not explain what observation data is captured, how the file_path is used, or what the outcome of recording is. Despite output schema existing, the description still fails to provide a minimal mental model.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention file_path or tool_name. An agent cannot infer the meaning of these parameters or the role of tool_name's default 'Edit' from the text. The description fails to compensate for the absent schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Record an observation explicitly' essentially restates the tool name and provides no detail about what constitutes an observation or how it differs from sibling recording tools like cos_metric_record or cos_work_log_append. The adverb 'explicitly' hints at manual capture but does not clarify scope or target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage conditions, prerequisites, or alternatives are mentioned. The description gives no indication of when to choose this over other record/log tools. It is tautological guidance: record an observation when you want to record an observation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states the action without disclosing behavioral details beyond the annotations. It does not mention WIP limits, validation rules, side effects, or whether transitions are logged. Since annotations already indicate a non-read-only mutation, the description adds minimal extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundancy, but it under-specifies the tool's behavior. While not verbose, it sacrifices needed detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's five parameters and its role in a stateful process, the description is incomplete. It does not address required inputs, prerequisites, state constraints, or the meaning of the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain any parameters. It does not clarify that 'to' is the target state, what 'reason' is used for, or the role of 'bypass_wip' and 'agent_session'. This leaves parameter semantics almost entirely to the agent's guesswork.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'transition' and identifies the resource 'a task' and the system 'Scrumban state machine', making the tool's core function clear. However, it does not explicitly differentiate from similar tools like cos_task_reposition, which might also move tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no context on when to use this tool versus alternatives such as cos_task_ready, cos_task_wip_check, or cos_task_reposition. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read-only operation. However, the description adds no behavioral context beyond the annotations; it merely restates the purpose without explaining what data is summarized, how the 'since' parameter affects output, or what the response format is. This is effectively a tautology of the title.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundant content, which is appropriately concise. It could have been slightly longer to include parameter hints without losing conciseness, but as is, it is not bloated and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is incomplete given the tool's complexity and 0% schema parameter coverage. It does not clarify the meaning of 'daily standup summary', the role of the parameters, or the context in which the tool should be invoked. A simple but more informative description would substantially improve usability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
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 by explaining the parameters, but it does not. The 'since' and 'agent_session' parameters are left entirely unexplained, forcing the agent to rely on parameter names and defaults alone. This is a critical gap for a 2-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses the verb 'Produce' with the resource 'daily standup summary', stating the tool's primary function. This is distinguishable from sibling tools like cos_task_show or cos_task_board, as none explicitly mention a daily standup summary. However, it lacks explicit scope details such as whose standup or what time period is covered, though the name and annotations reinforce the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites, or suggest any sibling tools. For a tool with many task-related siblings (cos_task_search, cos_task_board, cos_task_history), this is a significant omission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a small amount of behavioral context by mentioning 'scored' and the entry point categories, but it does not explain how scoring works, if any sorting is applied, or how pagination/limits behave.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no padding, which is concise. However, the trailing '— TASK-081.' is irrelevant for tool invocation and adds noise. The structure is minimal but not optimally informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters with no schema descriptions, an output schema, and many graph-related siblings, the description is inadequate. It does not explain how parameters affect results, what 'scored' means, or how this tool differs from alternatives, leaving significant gaps for an agent to navigate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no information about the four parameters (top, kind, diversify, min_score). It does not compensate for the missing schema descriptions, leaving the AI agent to infer meanings solely from parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource as 'entry points' and the action as returning 'Top-N scored' items, which clearly indicates a ranked list retrieval. It is distinct enough from sibling tools like cos_graph_ranking by focusing on entry point types (main/cli/http/cron/test), though an explicit verb like 'list' or 'get' is absent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as cos_graph_ranking, cos_graph_search, or cos_graph_query. The description provides no context about appropriate scenarios or exclusions, offering only a bare statement of what it returns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the atomicity of the claim and the null result behavior, which goes beyond the annotations that only state readOnlyHint, destructiveHint, and idempotentHint are false. However, it does not disclose side effects on task state, locking, or what happens if the claim fails, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It conveys the core action and a key edge case (claimed=null) economically, though the parenthetical is somewhat cryptic without further context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and an output schema, the description is too sparse to be complete. It lacks any parameter rationale, return value details beyond null, and does not mention how 'top' is determined or how session context influences the claim.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no explanation of the three parameters: swimlane, priority_min, and agent_session. The parameter names are self-explanatory to some degree, but the description adds no value in clarifying their semantics, defaults, or how they affect the claim selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool atomically selects and claims the top runnable task for the current session, with an explicit null return when none exists. It uses a specific verb phrase and resource, but does not explicitly differentiate from sibling tools like cos_task_pick or cos_task_reclaim.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for claiming the next task but provides no guidance on when to prefer this over alternatives, nor any exclusion criteria. No mention of when not to use it or how it differs from similar claim-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false, covering the safety profile. The description adds the 'zombie' condition and target state, but does not disclose side effects (e.g., changes to owner or timestamps), required permissions, or the existence of a dry_run mode. This is 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the key verb 'Reclaim' and resource 'zombie in_progress tasks'. It is concise and to the point, though the term 'icebox+ready' is slightly cryptic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three undocumented parameters and an output schema, this tool requires more contextual explanation. The description does not clarify what each parameter does, what 'icebox+ready' means in practice, or the default behavior when parameters are omitted. It is incomplete for an agent to use safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters (dry_run, idle_hours, agent_session) with no descriptions and 0% schema coverage. The description makes no mention of these parameters, leaving the agent completely in the dark about their meaning, defaults, or how they affect the reclaim operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (reclaim), the resource (zombie in_progress tasks), and the outcome (to icebox+ready). It includes a specific condition (idle + owner session inactive) that helps distinguish it from generic move or ready tools. However, the phrase 'icebox+ready' is somewhat ambiguous about whether tasks go to one state or both.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case (reclaiming zombie tasks) but provides no explicit guidance on when to use this tool instead of alternatives like cos_task_move, cos_task_ready, or cos_task_reconcile. There are no 'use when' or 'do not use when' instructions, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the specific metrics returned, which is useful context, but it does not disclose any additional behavioral traits such as pagination, data freshness, or return format. It is consistent with annotations, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise phrase that front-loads the core purpose and key metrics. It is appropriately sized for a simple tool, though it is not a full sentence and lacks detail. No unnecessary words are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description provides a basic summary of what is returned. However, it omits explanation of the 'since' parameter and does not give any context on typical usage scenarios. The presence of annotations and output schema reduces the burden, but the description still feels minimal given the amount of sibling tools and potential ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 only parameter 'since' is not mentioned in the description; the schema provides a title and default but no format or semantic explanation. The description's 'weekly' hint partially implies a time range, but it does not explicitly document how 'since' works or what values are accepted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as providing weekly retro metrics, listing specific metric types (cycle time, throughput, emergency count). This distinguishes it from daily or general metric tools, though it lacks an explicit verb like 'retrieve' or 'list'. It is specific and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The word 'weekly' implies a timeframe, but no exclusions or explicit alternatives are mentioned (e.g., cos_task_daily for daily metrics). The description does not help the agent choose between this and other metric/query tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden but only discloses the immediate effect of the 'decision' parameter (triggers backtrack recommendation vs stores for later). It doesn't mention side effects, permissions, or what the returned data looks like, though an output schema exists. This is partial disclosure but provides some behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loads the core purpose. It avoids redundancy and is easy to scan. However, it's arguably underspecified, but that's a completeness issue, not a conciseness issue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 required parameters, zero annotations, and an output schema present, the description should provide more context on what constitutes a discovery and how the fields relate. It only addresses the decision field, leaving significant gaps in how to fill the other required parameters and what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It only clarifies 'decision' with two example values ('backtrack_now', 'record_for_later'); the other 6 required parameters (kind, summary, impact_assessment, session_id, task_marker, persona_id) are completely undocumented in both description and schema. This leaves the agent guessing at their semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a verb ('Capture') and resource ('mid-work discovery'), and it distinguishes two decision modes ('backtrack_now' vs 'record_for_later') that give the tool a specific identity compared to sibling tools like 'cos_observation_record' or 'cos_backtrack_log'. However, it doesn't precisely define what qualifies as a 'discovery', leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('mid-work discovery') and describes two decision paths, but it doesn't explicitly state when to prefer this tool over siblings like 'cos_observation_record' or 'cos_backtrack_log'. The alternative 'record_for_later' vs 'backtrack_now' provides internal branching but no external guidance on when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context that the scan is 'header-only' and 'frontmatter' filtered, which is useful. However, it does not disclose behaviors like default limit handling, ordering, or whether frontmatter filters combine via AND/OR, leaving some gaps beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with no filler or redundancy. It is front-loaded with the key action ('Bulk header-only scan') and gives the filtering context. It is slightly telegraphic, but for a short description it is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description leaves significant gaps for a tool with six optional parameters and zero schema coverage. Although annotations cover safety and an output schema exists, the lack of parameter guidance makes it hard to know how to construct a correct filtered scan. The description is too minimal to be considered complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for six parameters, yet the description only mentions the high-level idea of frontmatter filtering. It does not explain how root, ssot, layer, limit, domain, or since_iso map to filtering behavior or how they should be used, so the description does not compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action—bulk header-only scan—on doc headers with frontmatter filtering, making the core purpose clear. It is not tautological and the title reinforces 'List Doc Headers by Frontmatter Filter.' It lacks explicit sibling differentiation, but 'bulk header-only' helps distinguish from singular or search tools like cos_doc_header and cos_doc_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a bulk, header-only scan of documents filtered by frontmatter is needed. It does not explicitly state when to prefer alternatives or when not to use this tool, so no exclusions or alternative guidance are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions 'without requiring Hub' and 'adapter-neutral' but does not disclose side effects, whether changes are reversible, required permissions, or what 'partially configure' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the main purpose. No filler words. However, it is so brief that it sacrifices important detail, though for a description of this length it is structurally clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 16 parameters and no annotations. The description provides almost no context about how configuration works, what options are available, or what the output contains. It is far from complete for such a complex tool, despite the output schema existing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention any of the 16 parameters. It provides zero guidance on how to map actions like 'enable' or 'disable' to parameters such as mode, action, or role_model.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs (show, enable, disable, partially configure) and identifies the resource (adapter-neutral supervision policy). It also provides scope (current project) and a key constraint (without requiring Hub), distinguishing it from sibling tools like cos_supervise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: whenever you need to inspect or modify the supervision policy. It provides context (current project, no Hub needed) but does not explicitly state when to prefer an alternative or exclude other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavior context: the tool returns a ranked list (top candidates) rather than a single task, and ranking by priority suggests a selection heuristic. This goes beyond the annotations and helps the agent predict the output shape. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence of ten words. Every word carries meaning: 'Return' sets the action, 'top candidate tasks' defines the resource, 'start next' clarifies the context, and 'ranked by priority' explains the ordering. It is appropriately concise with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 3 optional parameters and a long list of sibling task tools, the description is too sparse. Although an output schema exists (which reduces the need to describe return values), the lack of parameter documentation and usage guidance makes the tool hard to invoke correctly. The description covers only the surface purpose and leaves the agent uninformed about filtering and candidate selection specifics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention any parameters. The parameter names (swimlane, priority_min, max_candidates) are somewhat self-explanatory but lack details like allowed values, format, or how they affect the ranked results. The description fails to compensate for the lack of schema descriptions, leaving the agent to guess parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'top candidate tasks to start next, ranked by priority,' with a specific verb (return) and resource (candidate tasks). This distinguishes it from sibling tools that claim or modify tasks, though it does not explicitly name alternatives. The annotation title 'Pick Next Task to Work On' reinforces the intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like cos_task_claim_next or cos_task_ready. It does not mention any exclusions, prerequisites, or comparison with other task-related tools. The only implied context is 'to start next,' but that is more purpose than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by specifying that the history is actor-attributed and includes git commits, which informs the agent about the scope and nature of the returned data. It does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the core purpose and enumerates content types. It is concise and every word contributes to understanding the tool's scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three parameters and zero schema descriptions, the description should explain parameter meanings and default behaviors. It only hints at include_commits and does not address limit or the required task_id; the word 'full' may even mislead given the limit parameter. The existence of an output schema does not compensate for the missing parameter context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (task_id, limit, include_commits). The mention of 'git commits' hints at include_commits, but there is no elaboration on the limiting behavior of limit or the requirement of task_id. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as task history and enumerates specific content types (creation, status transitions, field edits, git commits), which distinguishes it from siblings like cos_task_show or cos_task_daily. However, it lacks an explicit action verb such as 'get' or 'list', making it a noun-phrase statement rather than a full action definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only states what the history includes, without mentioning that this is the audit-trail tool or that cos_task_show would be appropriate for current state, so the agent receives no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It provides valuable context: return fields, advisory thresholds (≥3/≥5 backtracks), the dependency of suggested_action on root_cause, and per-cause session counts. It does not mention side effects or error conditions, but the disclosed behavior is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It opens with the primary action, lists the return object, then uses three short sentences to explain each return field's meaning. Every sentence adds information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key behavioral logic (thresholds, conditional suggested_action, session-scoped summary) and return values, but it omits usage context and parameter semantics for a tool with 10 parameters and no annotations. It is adequate for basic invocation but incomplete for nuanced handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for ten undocumented parameters, but it only clarifies root_cause ('when root_cause is supplied') and indirectly session_id ('this session'). Most parameters (reason, from_formula, to_formula, hypothesis, etc.) remain unexplained, leaving a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Record a backtrack event') and identifies the specific resource type. It distinguishes itself from siblings by the term 'backtrack event,' though it does not explicitly contrast with other logging/query tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives like cos_observation_record or cos_log_query. The intended use is only implied by the phrase 'Record a backtrack event,' with no exclusions, prerequisites, or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the scope of enumeration (handler types) but does not disclose output format, filtering behavior, or potential performance implications. It provides some contextual value without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core action and clearly states the resource. There is zero wasted verbiage, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and annotations, the description is too sparse to support full invocation. It does not clarify how the parameters work, what 'scope' means, when to set include_test_sources, or whether the output includes details beyond handler names. With 3 parameters and 0% schema coverage, this description leaves significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters. Parameter names (kinds, scope, include_test_sources) offer some hints, but values, defaults, and effects are undefined. For example, 'scope' defaults to 'all' but its possible values are not explained, and the interaction between 'kinds' and 'scope' is unclear. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Enumerate' and clearly identifies the resource: 'every handler declared in the graph' with explicit handler types (HTTP / MCP / gRPC / events / WS). This distinguishes it from sibling tools like cos_graph_query or cos_graph_context, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only states what the tool does; it does not mention any exclusions, prerequisites, or relationships to other graph tools (e.g., cos_graph_entrypoints, cos_graph_search). An agent would have to infer usage context from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds 'MD frontmatter + sync', which reveals side effects beyond the annotation. However, it fails to disclose WIP enforcement or the role of the bypass_wip parameter, and the 'sync' behavior is vague. It adds some value but not substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 10-word sentence, front-loaded with the action verb. Every word contributes: 'Update', 'Scrumban status and/or swimlane', and the parenthetical about MD frontmatter and sync. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters and no parameter descriptions, the tool is under-specified. Even though an output schema exists, the description doesn't explain what happens when 'to' is empty, what 'agent_session' is for, or how the WIP bypass works. The lack of usage guidance and parameter semantics makes it incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 meanings. It only hints at 'status and/or swimlane' but does not explain what 'to' maps to, what 'reason' means, or how 'bypass_wip' affects execution. The parameter names in the schema are not self-explanatory, and the description doesn't clarify them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource: 'Update Scrumban status and/or swimlane'. It differentiates from siblings like cos_task_move and cos_task_edit by focusing on status/swimlane rather than general editing or moving, and the parenthetical 'MD frontmatter + sync' adds implementation detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or comparisons to cos_task_move or cos_task_edit. Users are left to infer usage solely from the name and brief description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent write operation (readOnlyHint=false, idempotentHint=false), so the description needs to add additional behavioral context. It does not; it merely restates the append behavior and gives a vague 'Critical' note with no details on side effects, permissions, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences and front-loads the primary purpose. The second sentence, 'Critical for Codex sessions,' adds context but is not strictly necessary; overall the description is efficiently structured without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple append tool with annotations and an output schema, the description covers the basic action adequately. However, it leaves gaps in parameter semantics and does not mention error conditions, prerequisites, or how the output is returned, making it minimally complete but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 by explaining parameters. It does not. While 'task_id' and 'summary' are somewhat self-explanatory, the purpose of 'source' and 'agent_session' is not clarified, and the description provides no parameter-level guidance whatsoever.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'append' and identifies the resource as 'Work Log line to a task', which is clear and distinct. It effectively differentiates from sibling tools that read, query, or edit tasks, and adds context by calling it 'Critical for Codex sessions'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Critical for Codex sessions' provides some context for when to use the tool, but it does not explicitly compare to alternatives or state when not to use it. The guidance is implied rather than concrete, leaving the agent uncertain about the exact conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full behavioral burden. It discloses the null output behavior and the override of persona primary_formulas, which are useful. However, it does not clarify whether the override is a persistent side effect or an in-memory setting, nor does it mention any permissions, rate limits, or other constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, efficiently front-loaded with the core action 'Classify'. It lists the categories in parentheses and the override behavior in a second sentence, with no extraneous words. This is an appropriate size for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core classification behavior, the possible outputs, and the null case, which is good for a simple tool. It also mentions the override side effect, but leaves the input format unexplained and provides no context on the persona or when to use this tool. Given the output schema exists, the return structure is likely covered, but the description is not fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single 'signals' parameter with zero description coverage, so the description must compensate. The description refers to 'a set of signals' and lists the classification categories, which gives some context about the content. However, it does not specify the expected format (e.g., JSON array string) or provide examples, leaving the parameter semantics underdefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool classifies signals into a specific set of situational dispatch chain IDs and returns null if none match. The verb 'Classify' and the enumerated categories make the purpose unambiguous. It also distinguishes itself by mentioning the override of persona primary_formulas, which sets it apart from generic classification siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool over others. It says what the tool does but does not mention alternatives, prerequisites, or conditions for invocation. The only implicit hint is that it is used when there are signals to classify, but it lacks the explicit 'when to use vs. when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no safety profile (all hints false), so the description carries the burden. It states 'Get' and 'Returns: str: JSON with full record,' signaling a retrieval operation, but it does not explicitly address whether the call is read-only, what happens on missing IDs, or any error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact with a clear one-line purpose and separate Args/Returns sections. Every sentence earns its place, with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter details fetch with an output schema, the description covers the arguments and return format sufficiently. It could add an example or note about error cases, but the current level is adequate for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds real meaning beyond the bare schema by explaining pattern_id as 'Row ID (or task_id string for task_outcomes)' and source as 'observations, learned_patterns, or task_outcomes.' The possible type mismatch with the schema's integer pattern_id is a minor concern, but the special case is still useful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get full details of a pattern, observation, or task outcome,' using a specific verb and specifying the resources. It is clear about the operation, though it does not explicitly differentiate it from sibling query tools like cos_search or cos_graph_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: given a row ID and a source table, retrieve the full record. It does not state when to choose this tool over alternatives, nor does it mention exclusions or prerequisites, so the guidance remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It clearly states a crucial trait: 'returns prompt text only' and explicitly denies spawning. This reveals the non-side-effect nature of the tool, though it omits preconditions or error behavior. Given no annotations, this is a solid disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, focused sentences with no fluff. It front-loads the main action and uses the final sentence to clarify a critical behavioral caveat. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists and the description covers the core purpose and non-spawning behavior, the complete absence of parameter semantics and minimal usage guidance leaves significant gaps. With 5 parameters and 4 required, the agent needs more context to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description contains no parameter explanations. Required parameters like `formula_id`, `session_id`, `task_marker`, and `persona_id` are not defined in either the schema or the description, leaving the agent without any semantic grounding for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and precise resource ('rendered agent prompt and input slice for a formula-agent'). It also distinguishes itself from the likely sibling `cos_dispatch_formula_run` by explicitly stating 'Does NOT spawn the subagent'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context: 'The main agent uses this to construct the subagent dispatch.' It also gives a clear exclusion with 'Does NOT spawn the subagent.' However, it does not explicitly name an alternative tool for when spawning is desired, so it's not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar for additional disclosure is lower. The description adds useful behavioral details: empty files produce an empty envelope, analyze_downstream walks transitive blast radius, and scope is 'Label only' with allowed values. However, 'Label only' is ambiguous and the effect of scope on results is not explained, so transparency is only partially enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly efficient: one front-loaded purpose sentence followed by a compact Args list. Every sentence adds value, and there is no repetition of annotation or schema information. This is a model of concise tool documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all three parameters, the empty-input edge case, and the core analysis dimensions (symbols, downstream tasks, risk level). Since an output schema exists, not detailing return values is acceptable. Minor gaps remain around the meaning of 'scope' and how risk level is determined, but overall the description is adequate for a three-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for parameter semantics. It explains files as comma-separated paths with empty-input behavior, lists valid scope labels, and describes analyze_downstream as transitive blast-radius traversal. The scope explanation is limited to 'Label only' plus allowed values without defining what each scope means, preventing a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Map changed files to affected symbols + downstream tasks + risk level.' This clearly identifies the tool's purpose as change-impact analysis. It does not explicitly differentiate from sibling tools like cos_graph_diff or cos_graph_impact, but the unique output dimensions (downstream tasks, risk level) make the purpose clear enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'changed files' and the annotation title 'Graph Pre-Commit Self-Review,' and the Args block provides practical input guidance. However, the description never explicitly states when to use this tool instead of sibling graph tools, nor does it mention any exclusions or alternatives. This is implied usage rather than explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It transparently states the two side effects (appending to EvidenceBundle and recording in formula_dispatches) and enumerates status values. However, it omits details such as idempotency, overwrite behavior, permissions, or failure consequences, leaving notable behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, starts with the primary action, and packs essential usage timing and status enumeration into a compact form. Every sentence adds value and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the tool has 7 parameters with zero schema descriptions and no annotations. The description provides the high-level purpose and when to call, but does not explain parameter semantics or relationships, nor does it discuss edge cases. This is incomplete for a moderately complex tool, especially as the description must compensate for the absence of per-parameter documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only adds meaning for 'status' by listing accepted values (ok|fail|timeout). The other six parameters receive no explanation, thus the description adds minimal value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool appends a formula-agent's output to the session EvidenceBundle and records the dispatch in formula_dispatches. The verb 'append' and specific resources provide a clear, distinct purpose among sibling tools, and the call-after hint reinforces its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Call after each formula-agent returns' provides an explicit condition for usage, which is clear context. However, it does not mention when not to use or name alternative tools, so it lacks exclusions/alternatives that would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which already indicate this is a mutating, non-idempotent operation), the description adds that each change is recorded to an actor-attributed edit history. This is useful behavioral context not present in the annotations. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single, front-loaded sentence that states the main purpose and the key audit behavior. Every word earns its place, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 11 parameters, is a mutation operation, and has an output schema, the description is too sparse. It does not clarify update semantics (e.g., merge vs. replace), which fields are considered frontmatter, or the roles of actor-related parameters. The output schema exists but cannot answer these behavioral questions. This is a clear gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not enumerate or explain any of the 11 parameters. While some parameter names are self-explanatory (title, body, priority), others like actor_id, actor_type, source, and labels_csv lack behavioral meaning. The description fails to compensate for the schema's lack of textual detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Edit') and resource ('task's frontmatter fields and/or body'), clearly distinguishing it from creation, moving, or viewing tools. The actor-attributed history note adds important scope. This is a clear, non-tautological purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying existing tasks but provides no explicit 'when to use' or 'when not to use' guidance, nor does it mention alternatives among the many sibling task tools. It is adequate but relies on the reader to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description reveals key behavioral traits: 'Read-only', 'Idempotent and non-blocking'. This goes beyond the minimal safety profile and gives useful operational context, though it does not explain what happens on failure or what 'matching evidence' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences plus a scope hint. It is front-loaded with the core purpose. The trailing 'scope: task|project' is somewhat disjointed but not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and key behavioral traits but lacks background on what 'doc anchors' and 'formula dispatches' represent or what constitutes 'matching evidence'. With no annotations and limited parameter explanation, it is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only clarifies the 'scope' parameter as 'task|project'. The required parameters session_id, task_marker, and persona_id are left undefined, leaving the agent with no semantic guidance beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'read-only audit' that verifies tasks have doc anchors and recent formula dispatches have matching evidence. This specifies a concrete action and target, distinguishing it from sibling tools like cos_retrieval_cite or cos_retrieval_quality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for verifying traceability and mentions it is read-only and idempotent, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. No alternative tool is named, so usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses the internal decision strategy ('situation override > preset match > per-role scoring composer > hard fallback') and states the return type with provenance fields (preset_id, preset_version, effective_threshold, activations). This adds meaningful behavioral detail, though it does not mention side effects, error handling, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and every word adds value. The first sentence states the core purpose, the second provides the strategy and output details. No redundant or filler content exists, making it efficient and well-front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four parameters, no annotations, and a schema with zero descriptions. The description gives a high-level overview and mentions the return type (with an output schema available), but it omits critical input details and usage prerequisites. It is not fully complete for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 parameter descriptions. The description does not explain the meaning or structure of signals_json, nor how session_id, situation_id, or preset_min_score map to the strategy. It only vaguely references concepts like 'situation override' and 'preset match' without tying them to specific parameters. Since the description fails to compensate for the missing schema documentation, parameter semantics are weak.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'Compose an ordered formula-role chain from TaskSignals.' It uses a specific verb ('compose') and a specific resource ('formula-role chain from TaskSignals'), and the strategy details further clarify the behavior. This distinguishes it from sibling tools, which are mostly about tasks, graphs, or learning rather than chain composition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool by explaining the composition strategy and the output provenance, but it does not explicitly state usage conditions, prerequisites, or alternative tools. There is no mention of when not to use it or how it relates to sibling tools like cos_dispatch_formula_run. The usage context is implied rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Creates file content but does NOT write to disk', which directly contradicts the annotation readOnlyHint=false that implies the tool may have side effects. This is a serious inconsistency. While the description does add useful behavioral context (e.g., return format, confidence threshold), the contradiction warrants a score of 1.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose, a prerequisite line, a behavioral line, and clean Args/Returns sections. Every sentence adds value, and the most important information (purpose, side-effect-free generation) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two parameters, the description is complete: it specifies the prerequisite, the non-writing behavior, the caller's responsibility, and the return format. It provides enough context for an agent to invoke it correctly and handle the output, even without an explicit output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero descriptions (0% coverage), so the description shoulders the full burden. It explicitly documents pattern_id as 'ID in learned_patterns table' and target as an output type with allowed values 'feedback' or 'rule', fully compensating for the schema's lack of explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Promote a validated pattern to a rule or feedback memory file', giving a specific verb and target resources. It distinguishes from sibling tools by focusing on promotion of already validated patterns, not validation or suggestion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a key precondition (confidence >= 0.3) and explains that the tool does not write to disk, implying it should be used as a content generator with caller-driven persistence. However, it does not explicitly mention when to use this tool over alternatives or provide exclusions relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context about keyset pagination and how to fetch additional complete/archive items via cursor and status_filter, which is beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose and a concise pagination note. Every word earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core grouping and pagination behavior, and an output schema exists to explain return values. However, with 8 optional parameters and no guidance on their purpose or interactions, the description is not fully complete for a complex filtering tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only explains cursor and status_filter in the context of pagination, leaving the other six parameters (epic, kind, limit, swimlane, page_size, include_archive) unexplained. This is insufficient for a tool with 8 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns board state grouped by (swimlane, status) with WIP info, using a specific verb ('Return') and a distinct resource. This differentiates it from sibling tools like cos_task_search or cos_task_daily, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving board state but does not explicitly state when to use it over alternatives or provide exclusions. The pagination note gives some usage direction for loading more results, but there is no comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses return semantics (violations list, empty = pass), the trigger timing, and the exclusion for CLEAR 1 tasks. It does not explicitly state read-only/side-effect behavior, but the 'check' verb and return-focused wording imply a non-mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action and result. Every sentence adds value: the purpose, the return format/interpretation, and the trigger/exclusion rules. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, output semantics, and trigger conditions, and an output schema exists to define return structure. However, the lack of parameter documentation prevents an agent from confidently assembling a correct invocation, making it only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the three required parameters. It only vaguely hints at session_id via 'session EvidenceBundle' and task_marker via 'CLEAR 1 tasks', but provides no explicit explanation for any parameter, especially persona_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Run') and resource ('7-criteria Anti-Ambiguity gate over the session EvidenceBundle'), making the tool's purpose immediately clear. It does not explicitly contrast with sibling tools, so it misses the highest distinction criterion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when the tool fires ('PLAN→EXECUTE') and when it should be skipped ('CLEAR 1 tasks skip this check'). This provides clear usage conditions and exclusions, which is more than most tool descriptions offer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, idempotent operation. The description adds a concrete side effect: inserting new patterns into learned_patterns with calculated confidence. It does not contradict the annotations and provides useful behavioral context beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear purpose, effect, args section, and return type. It contains no redundant information and each sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description covers the core aspects: purpose, detected patterns, insertion behavior, parameter meaning, and return format. It could be more detailed about the analysis stats, but is largely complete given the available structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains the only parameter (min_occurrences) as the minimum occurrences to consider a pattern, with a default of 3. This adds meaningful semantic information beyond the raw schema type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it scans task outcomes to discover recurring patterns, listing specific pattern types (domain_rework, skill_correlation, complexity_mismatch). It also mentions inserting into learned_patterns, distinguishing it as an extraction/write tool, though it doesn't explicitly compare to sibling learning tools like cos_learn_suggest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for discovering patterns from task outcomes, but provides no explicit guidance on when to use this tool versus alternatives such as cos_learn_suggest or cos_learn_validate. It lacks 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: it filters to WARN+ severity and returns most-recent-first. This helps the agent understand the data shape and ordering, though it doesn't cover all behaviors like pagination or filtering semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It packs the verb, resource, constraints, and purpose efficiently, earning a perfect score for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 optional filter parameters with no schema descriptions, making it a flexible but complex query tool. The description covers core purpose and basic behavior but misses any guidance on parameter usage, filter combination, or edge cases. Even with an output schema present, the agent is left under-informed about how to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no information about the 8 parameters. Only 'WARN+' hints at the 'level' filter and 'most-recent first' at ordering, but the agent gets no guidance on 'scope', 'since', 'search', 'trace_id', 'session_id', or 'fingerprint'. The description fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Query'), names the resource ('durable log_events store'), and states key constraints ('WARN+', 'most-recent first'), plus a clear purpose ('what is broken now'). This clearly differentiates it from siblings like cos_metric_query and cos_failure_pattern_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "the agent's 'what is broken now'" clearly implies this is for diagnosing current problems, but it does not explicitly name alternatives or state when not to use it. The context is clear, though no exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the transparency burden. It implies a read-only operation ('Return metadata') and lists the output fields, adding some value, but it does not mention error behavior, invalid role_id handling, or explicitly confirm no side effects. This leaves some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long. The first sentence states the action and output fields, and the second adds a clear usage hint. There is no redundancy or filler; every clause earns its place, and the description is properly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description covers the primary purpose, usage context, and output fields. The main gap is the unclear meaning of role_id, but the output schema handles return value structure. Overall it is nearly complete for a metadata lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter (role_id) with no description coverage. The phrase 'formula-role (researcher..refactorer)' hints that role_id should be one of these role names, but it does not explicitly connect role_id to that list or specify the expected format. The agent must infer the value semantics, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Return' and clearly identifies the resource as 'formula-role' and the exact metadata fields returned (prompt_prefix, tools_budget, etc.). This distinguishes it from the many sibling tools that focus on tasks, graphs, or dispatch, none of which provide role metadata lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Useful for the main agent before dispatch,' giving a clear context for when this tool should be used. It does not mention alternatives or when not to use it, but the 'before dispatch' hint is specific enough to guide the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly reveals the critical behavioral trait that the tool never spawns agents, only advises the main agent, which mitigates a key risk. However, it does not detail potential statefulness, side effects on session state, or authentication requirements, leaving some behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. It front-loads the core purpose, then provides a usage sequence and a key constraint. Every sentence adds value and is directly relevant to invoking the tool correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a complex supervisor with 9 parameters and no annotations, yet the description only covers the high-level loop and one behavioral constraint. It leaves the agent without guidance on how to set the many parameters and what the output schema contains (though an output schema exists). Given the complexity, the description is incomplete for correct invocation of all parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 9 parameters with 0% description coverage, and the description adds no information about what parameters like phase, pending, intensity, dispatched, situation_id, or backtrack_count mean. The only hint is that the tool is called after recording output, but this does not explain the required session_id, task_marker, or persona_id. The description completely fails to compensate for the undocumented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Return the next action') and enumerates the possible outcomes (dispatch, backtrack, signal done). It also distinguishes itself from sibling dispatch tools by explicitly stating it never spawns agents itself, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Call repeatedly after recording each formula output via cos_supervise_record_output' establishes the intended workflow and sequencing. The statement 'Never spawns agents itself — only tells the main agent what to dispatch' clarifies when not to use this tool for actual dispatch, making the usage context very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It adds valuable behavioral information: under 500ms, cached per task_marker, and takes optional memory/graph context. It does not mention side effects, but for an extraction tool this is likely non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. Three sentences: first states purpose and inputs, second gives historical context, third provides performance/caching. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, reducing the need to describe return values. The description covers purpose, performance, caching, and input sources, but the 0% parameter coverage leaves a significant gap, making it incomplete for full usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only hints at 'prompt' and 'task_marker' (via caching), leaving complexity, dimensions, session_id, and project_dir completely unexplained. This is insufficient for 6 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Extract') and resource ('TaskSignals') from a prompt with optional context, listing the signal fields. It also differentiates from legacy 'persona keyword matching', making its purpose distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: use this to extract structured TaskSignals from a prompt, and explicitly states it replaces persona keyword matching. However, it does not offer explicit when-not-to-use guidance relative to sibling tools like cos_classify_prompt.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description bears the full transparency burden. It discloses concurrency (asyncio.gather), side effect of persisting outputs to the bundle, and return behavior (list in input order). This is useful, though it omits failure semantics and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences deliver purpose, trigger, and behavior without padding. Front-loaded main action, efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core context but, with 10 parameters and no schema descriptions, lacks parameter semantics; output schema mitigates return-value ambiguity. Failure handling and edge cases are absent, so it's not fully complete for a parallel-dispatch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description offers almost no parameter-level explanation. 'Formula-agents' loosely maps to formula_ids, but values like session_id, task_marker, persona_id, model, effort, intensity, timeout_s, and complexity remain unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'spawn' plus 'multiple formula-agents concurrently' clearly identifies what the tool does. The mention of asyncio.gather distinguishes it from sibling cos_dispatch_formula_run, which likely handles single dispatch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly states 'Use when the supervisor returns action='dispatch_parallel'' (with example context), providing a clear trigger. It does not name alternatives or exclusions, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states that setting fix=true will 'attempt safe repairs (delete dangling edges)', which is a destructive/write operation. However, annotations declare readOnlyHint=true and destructiveHint=false, creating a direct contradiction. This is a severe inconsistency that could mislead the agent into thinking the tool is safe and read-only when it can modify data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured: purpose is front-loaded, usage trigger is given, parameters and returns are clearly bulleted. Every sentence earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter) and the presence of an output schema, the description covers all necessary aspects: purpose, when to call, parameter semantics, and return envelope. It even mentions the safe usage pattern (report-only first), making it complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides the parameter name 'fix' with a default, but the description fully explains its meaning, including conditional behavior (repair vs. report-only mode) and a recommendation to use report-only first. This adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as a 'Graph health snapshot' and lists specific issue types (orphans, dangling edges, duplicates, backend status). This distinguishes it from sibling graph tools like cos_graph_query or cos_health by focusing on integrity diagnostics rather than querying or general health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit trigger conditions: 'Call when graph queries return nothing or meta.backend_fallback=true.' This gives clear context for when to use it, though it doesn't explicitly mention alternatives or when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It transparently states that the tool mutates session state (sets the situation to existing-project-takeover, picks a persona) and produces an initial output (a dispatch action). It does not address reversibility or permissions, but for a bootstrap tool this level of disclosure is adequate and non-contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core verb 'Bootstrap,' and every clause adds meaningful detail. There is no redundancy or filler, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, usage context, and behavioral output, and an output schema exists to document return values. However, the complete absence of parameter semantics and the lack of annotations leave gaps for an agent to correctly invoke the tool, especially regarding task_marker and repo_description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter-specific guidance. The parameter names (session_id, task_marker, repo_description) are somewhat self-explanatory, but the description does not explain required formats, the meaning of task_marker, or how repo_description influences behavior, leaving invocation ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a verb ('Bootstrap') and a resource ('existing-project-takeover session'), and goes further by specifying the exact side effects: sets the situation, picks the legacy-maintainer persona, and returns the first dispatch action. This specificity distinguishes it from sibling tools like cos_situation_detect or cos_task_daily.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit usage condition: 'Use when inheriting a legacy repo with no docs.' This gives the agent clear positive guidance on when to invoke this tool. It does not mention exclusions or alternatives, but the context is unambiguous enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool costs ~5k tokens, rebuilds context, is opt-in, and returns status='skipped' without an SDK. These behavioral details go beyond what annotations typically provide, and since no annotations are present, the description carries the full burden effectively. The context rebuild penalty and opt-in nature are valuable transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear hierarchy: purpose, cost/behavior, alternative, use conditions, and fallback. Each sentence adds value, and the length is justified by the amount of guidance. It's front-loaded with the core action, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the 10-parameter input with zero schema documentation leaves the agent guessing about required arguments. The description covers when to use the tool but not how to properly invoke it, making it incomplete for a complex tool with this many parameters. The guidance focuses on decision-making rather than invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 10 parameters with 0% description coverage, and the description provides no details on the meaning of formula_id, session_id, task_marker, persona_id, or optional fields like model/effort. The only allusion is 'role' which loosely maps to persona_id but is never explicitly connected. This is a critical gap for a tool with four required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'EXPLICIT, OPT-IN sub-agent spawn for one role' which identifies the action (spawn) and resource (sub-agent for one role). It distinguishes from siblings like cos_dispatch_parallel_run by specifying 'for one role' and from cos_dispatch_formula by noting this is the explicit/opt-in variant. The fallback behavior further clarifies 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'PREFER lazy-loading' and gives an alternative approach with reasoning ('same accuracy, far fewer tokens'). It provides two concrete conditions for using this tool: '(a) the role's work is long-running' or '(b) you explicitly want a separate session for parallelism.' It also explains when to skip if no SDK is available. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the key behavioral trait that the body is not read, which is useful efficiency context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and resource, with zero waste. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and an output schema, the description plus the annotations title provides sufficient context. It does not need to explain return values because the output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'path' parameter. Although the parameter name is self-explanatory, the description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a single doc's header without reading the body, using a specific verb and resource. This distinguishes it from siblings that read full docs or multiple headers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: fetch only the header for efficiency. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full marks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description builds on that by adding concrete behavior: difflib baseline, auto-resolution of raw repo paths to code:file:/doc:file:/folder: namespaces, and a confidence threshold. This exceeds the structured hints without contradicting them, though it does not detail output shape or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a tight docstring with a one-sentence purpose followed by structured, scannable argument definitions. Every sentence adds value and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations and existing output schema, the description covers input semantics and safety sufficiently. The main gap is lack of mention of behavior when uid is not found or confidence_min is outside bounds, but the tool is still well-positioned for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It defines uid as fully-qualified with auto-resolution, top_k as the number of similar nodes, and confidence_min as a 0.0–1.0 similarity threshold. This adds substantial semantics beyond the bare schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action: 'Return the top-K nodes most similar to `uid`', naming the resource (nodes), the operation (similarity retrieval), and the algorithm (difflib baseline). This clearly distinguishes it from sibling graph tools like cos_graph_search or cos_graph_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides how to call the tool (uid resolution, top_k, confidence_min) but gives no explicit guidance on when to use this tool versus alternatives. The only cross-reference, 'see cos_graph_impact for scheme', is about UID format, not usage selection or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it 'Creates a high-impact learned pattern' and discloses the return format (status, history_id, pattern_id), adding value beyond the annotations. The annotations already indicate a write operation (readOnlyHint false), and the description aligns with that without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: purpose, trigger, bullet points of what to capture, args, and returns. Each section is concise and serves a clear function, though slightly longer than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage context, parameters, and return value. It does not address the relationship with other learn tools or clarify the optionality of key_insight, but the presence of an output schema and annotations partially compensates. Overall it is sufficiently complete for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are described with brief explanations, which is critical given 0% schema coverage. However, the description marks key_insight as 'required' while the schema lists it as optional with a default, and fails to note that task_id is the actual required parameter. This inconsistency could mislead the agent during invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Record what was learned from a difficult task (breakthrough narrative),' providing a specific verb and resource. It clearly distinguishes itself from sibling learn tools by focusing on post-rework success narratives and capturing failure/success/insight.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger: 'Call this after a rework→success breakthrough.' This tells the agent exactly when to use it. However, it does not mention alternatives or exclusions, so it lacks the explicit 'when not to use' that would merit a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful context beyond annotations by explaining the role of the 'ready' label in the workflow. Annotations already indicate idempotency and non-read-only behavior, and the description does not contradict them. It clarifies the mutation's purpose without needing to repeat safety traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately states the action and purpose. No unnecessary words or redundancy; it is front-loaded with the core verb and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description is mostly complete. It explains the tool's role in the workflow, and an output schema is present, so return values are covered. However, it lacks explicit parameter guidance and alternative tool references, which are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 explaining parameters. It mentions the 'ready' label, which maps to the 'ready' boolean parameter, but it does not explain task_id or agent_session. This leaves parameter semantics largely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Add or remove the ready label that gates icebox→in_progress.' It identifies the specific resource (the ready label) and the action (add/remove), and distinguishes it from sibling tools like cos_task_move or cos_task_edit by focusing on the gate label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by explaining that the ready label gates the transition from icebox to in_progress, implying when this tool is useful. It does not explicitly mention alternatives or exclusions, but the context is sufficiently clear to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that by specifying the output includes completion evidence and a review recommendation, giving agents a sense of what to expect. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every phrase ('Triage', 'stranded in_progress/testing tasks', 'completion evidence', 'review recommendation', 'read-only') earns its place, though 'read-only' duplicates the annotation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, strong annotations, and an output schema), the description is largely sufficient: it communicates purpose, scope, and output nature. The only notable gap is the unstated semantics of include_active, but since it defaults to false and has no required equivalent, the invocation risk is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides one boolean parameter (include_active) with no description (0% coverage), and the description does not mention it at all. This leaves the meaning of the flag and its effect on the stranded-task scope unclear; the parameter name gives only a partial clue.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Triage' with a clear resource ('stranded in_progress/testing tasks') and the added outcome ('completion evidence + a review recommendation'), making it distinct from other cos_task_* tools. It also explicitly marks the tool as read-only, reinforcing its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's intended use is clear: reconcile/triage stranded tasks in specific states, which gives an agent a clear trigger condition. It does not explicitly name alternatives or exclusion criteria compared with sibling tools like cos_task_reclaim or cos_task_show, but the target scenario is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds useful context by specifying the output content (frontmatter fields and full markdown body), which goes beyond the structured hints without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately conveys the core action, scope, and usage context. Every phrase serves a purpose, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool with strong annotations and an output schema, the description covers purpose, output contents, and usage context. The only notable gap is explicit parameter behavior, but this does not undermine overall usability for a straightforward inspection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description needed to explain the parameters, but it only indirectly references task_id via 'single task' and the body via 'full markdown body'. It never explains that include_body can be set to false to omit the body, leaving ambiguity about a key parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Show'), the object ('a single task's frontmatter fields and full markdown body'), and distinguishes this tool from siblings by focusing on a single task and positioning it as an alternative to raw ls/grep/Read. This is a specific, well-differentiated purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'in-session alternative to raw ls/grep/Read on docs/tasks' gives clear guidance on when to use this tool over generic command-line or file access methods. It does not explicitly mention sibling task tools or exclusions, but the context is sufficient for a read-only inspection scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses that the tool is heuristic, sub-second, deterministic, makes no LLM call, and optionally writes a gate marker. This gives a clear safety and performance profile, though the effect of the `record` parameter on persistent state is not explicitly described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the core purpose and output, followed by the side effect and key performance characteristics. Every sentence adds distinct value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema covers return-value details, so the description's focus on behavior, side effects, and workflow replacement is appropriate. The main gap is the missing explanation of `record` and `agent_dir`, which prevents it from being fully self-contained for parameter-level usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 explains `prompt` as the user prompt being read, and loosely implies `record` via the optional gate-marker write. However, `agent_dir` is completely unexplained, and the role of `record` remains ambiguous. The description provides partial but not complete parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('classifies', 'reads', 'returns', 'writes') and identifies the exact resource and output structure ({complexity, dimensions, reasoning, signals}). It also distinguishes itself from sibling tools by defining its unique role as a heuristic classifier with an optional gate-marker side effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says it replaces a manual `write-state.sh .thinking_os-gate` step, giving concrete when-to-use context tied to the enforce-task-start.sh workflow. It does not list alternative tools to use instead, but the guidance is strong enough to understand the primary use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which cover safety. The description adds context by detailing the use of `git diff --name-only`, mapping to symbols and downstream consumers, and the ability to walk transitive consumers, which goes beyond the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line summary, a method paragraph, an Args list, and a Returns section. Every sentence contributes to understanding, with no unnecessary repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description is sufficiently complete. It explains the workflow, parameters, and return envelope keys, and provides enough context for an agent to select and invoke the tool, though it could benefit from a brief example or note on interpreting risk_level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description compensates with an Args section that explains each parameter (base, head, analyze_downstream) and provides defaults and semantics. This adds meaningful value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Graph blast-radius of a git revision range (base..head)' with a specific verb and resource. It further explains the process and output, distinguishing it from sibling graph tools that focus on other analyses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context via 'PR/review view' but does not explicitly state when to use this tool over alternatives or mention any exclusions. No sibling tool is named as a fallback or alternative, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive. Description adds behavioral context: max_nodes hard cap, include_spine ancestor-chain behavior, mode view-blend semantics, and exclude_kinds sentinel defaults. These go beyond annotations, though references like 'S3' and 'TASK-141' are insider-cryptic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Lead sentence states purpose, then a compact arg list. Each param earns its place. Slight deduction for cryptic inline refs ('S3', 'TASK-141') that could be clarified without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-param export tool with rich annotations and an output schema, the description covers behavior and defaults well. Missing explicit return-value prose, but output schema covers that; lack of when-vs-alternatives keeps it from 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 7 params at 0% description coverage, so the description carries full burden. It explains every parameter: format values, root_uid semantics, edge_types filter, max_nodes cap, include_spine chain, mode options, exclude_kinds sentinel. This substantially adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Export a subgraph as json | mermaid | dot', a specific verb+resource+output formats. It clearly differentiates from sibling graph tools (query, search, context) by focusing on export. The formatting and parameter list reinforce purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the export verb and parameter explanations (e.g., root_uid empty, mode when no root pinned), but never explicitly states when to choose this over alternatives like cos_graph_query or cos_graph_search. No when-not or alternatives named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safe, read-only nature. The description adds behavioral context by specifying the lookback window, domain filtering, limit, and the exact structure of returned entries (id, title, date, outcome, type), going beyond the annotation-only safety profile. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-organized: a one-sentence purpose statement followed by clearly structured Args and Returns sections. Every sentence adds value, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 optional parameters, read-only, no side effects) and the presence of annotations and an output schema, the description covers everything needed: what the tool does, how to configure it, and what it returns. It is fully adequate for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no property descriptions (0% coverage), so the description fully compensates by explaining each parameter: days with range and default, domain with an example, and limit with range and default. This provides complete meaning beyond the bare schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Get recent task outcomes and observations timeline.' It explicitly describes the return format, making the purpose unambiguous. However, it does not explicitly differentiate itself from sibling query tools like cos_task_daily or cos_log_query, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when a timeline of task outcomes and observations is needed—but does not provide explicit alternatives, exclusions, or context for choosing it over similar tools. There is no mention of 'instead of X' or 'use this when', so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the return format ('JSON with total count and matching rows') and limits (1-100, default 20), which are useful behavioral details beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose, an Args list, and a Returns line. Each parameter gets a single line with name, explanation, and optionality. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query tool with optional filters, the description covers the input semantics and the return format. Given an output schema exists, detailed return values need not be spelled out. It could mention filter combination semantics (e.g., AND) but overall is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility. It documents all 7 parameters with examples, formats, and constraints (e.g., ISO dates, limit range). This fully compensates for the empty schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Query agent metrics with optional filters', a specific verb+resource+scope. It clearly indicates a read-only retrieval operation, distinguishing it from sibling tools like cos_metric_record (recording metrics) and cos_metric_trend (trend analysis).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are mentioned. The description implies usage for filtering raw metrics, but doesn't contrast with cos_metric_trend or cos_metric_record. There's no exclusionary guidance, so agents must infer when this tool applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, establishing a safe read-only operation. The description adds parameter constraints (metric allowed values, window range 1-365, group_by options) and the return structure (trends array with period, counts, rate), which goes beyond the annotations and enriches behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with a clear Args/Returns layout. Every sentence provides essential information, and there is no redundant or verbose content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query tool with three parameters and an existing output schema, the description sufficiently covers inputs and the high-level return shape. It could add an example or clarify the meaning of 'period' in the trends array, but overall it is complete and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), so the description fully compensates by enumerating all three parameters, their allowed values, defaults, and semantics. For example, it specifies that window_days is a lookback window (1-365, default 30) and groups by domain, model, agent_type, or complexity, making the tool immediately usable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get aggregated trend data for agent metrics,' clearly indicating a specific verb (get) and resource (agent metrics) with a focus on trends. This differentiates it from sibling tools like cos_metric_query and cos_metric_record, which likely handle direct lookups or recording.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied by the purpose—aggregated trend analysis—but the description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It provides no guidance on choosing between this and similar metric tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral details: the cold-start fallback to a static default, warm queries over success rates, and the JSON return structure. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (intro, Args, Returns) and is front-loaded with the main purpose. Every sentence contributes value: the cold/warm logic, parameter details, and return type are all relevant and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity, the description covers the essential aspects: the decision logic, parameter semantics, and return format. It does not mention potential errors or more detailed output field descriptions, but the presence of an output schema and annotations reduces the need. Slightly more detail on the fallback_model and performance.md would elevate completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It thoroughly explains each parameter: complexity with Cynefin enum values, dimensions with a default, and domain with an example and optional status. This compensates fully for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Recommend optimal model') and resource ('based on historical outcome data'), clearly distinguishing it from sibling tools like cos_route_skill. It further clarifies the cold-start and warm-start logic, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when the tool is used (cold vs warm), but it does not state explicit alternatives or when-not-to-use. Given the presence of cos_route_skill and other route-related siblings, naming an alternative would have improved guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses valuable behavioral details beyond the annotations: validation against a config file and enum, the effect of ready=True on pullability, and the DoR-satisfying behavior for bug-kind tasks. The annotations only indicate readOnlyHint=false, so the description adds meaningful context about internal behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the core purpose. Every sentence earns its place: the purpose, the preference over YAML, validation behavior, and special-case parameter guidance. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large parameter count (15) and zero schema-level descriptions, the description covers the essential create workflow but omits the meaning of many optional parameters. It does not explain fields like epic, labels, status, or depends_on. An output schema exists, so return values are not needed, but the description leaves gaps in understanding the full parameter set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema_description_coverage at 0%, the description must compensate for missing parameter explanations. It adds semantic meaning to key parameters (swimlane, kind, ready, acceptance, repro) but leaves many others (epic, labels, status, depends_on, read_first, agent_session) completely unaddressed. This partial coverage is useful but incomplete, earning a mid-range score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create a new Scrumban task file + sync to DB.' This is a specific verb+resource combination that distinguishes it from siblings like cos_task_edit or cos_task_move. The description also mentions validation against scrumban-config.yaml and the 8-value enum, further scoping its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Prefer this over hand-writing YAML,' giving a direct alternative. It also provides situational guidance: when to use ready=True and when to pass acceptance/repro for bug-kind tasks. This clearly communicates the intended use case and when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds the 'lightweight' and 'current' context, indicating a real-time, low-cost operation. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence that immediately conveys the tool's purpose. No wasted words, front-loaded with the key action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, a straightforward purpose, an output schema, and strong annotations, the description is sufficient to understand what the tool does and when to invoke it. No additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. The description adds no parameter details because none exist, and the schema is trivially complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('check') and resource ('current WIP counts vs. configured caps'). It distinguishes this tool from siblings by focusing on WIP caps, a specialized health check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'lightweight check' implies a quick status check, but no explicit guidance is given about when to use this versus alternative tools like cos_health or other task-related functions. The usage context is implied but not clearly delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context such as the auto-resolution of entry_uid (file → code:file: then entry-point heuristic), the meaning of terminal edge labels, and the max_steps cap. It does not contradict annotations, but omits details about include_external behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a one-line summary followed by a focused Args list. It is concise, front-loaded, and provides necessary parameter details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex with four parameters and an output schema. The description covers the required entry_uid and the key behavioral controls (terminals, max_steps) well, and defers to cos_graph_query for uid resolution. The missing include_external parameter and lack of output format discussion (though output schema exists) keep it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description's Args section is essential. It explains entry_uid with an example and resolution logic, defines terminals as edge labels, and describes max_steps. However, it omits the include_external parameter, leaving it undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Forward execution walk from `entry_uid` until terminals', which clearly identifies the tool as a forward graph traversal from a given uid. It includes an example uid format and differentiates from sibling tools like cos_graph_query and cos_graph_path by focusing on execution tracing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context: use when you need to trace execution forward from a known entry_uid. It advises running cos_graph_query first if unsure, which is an explicit prerequisite. However, it does not name alternative traversal tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the exact statistics returned and noting the return type (JSON string with keys tables, schema_version, fts5_available, db_size_bytes, rag). This goes beyond annotations and helps the agent understand the tool's output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: a one-line summary, a usage sentence, and a Returns block. There is no redundant filler. The Returns block is slightly redundant given the output schema but provides immediate clarity for the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only health-check tool, the description is complete. It covers what the tool does, when to use it, and what it returns, while annotations cover safety and idempotency. No gaps are evident, and the output schema and return key list make the contract clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so description cannot add meaning beyond the schema. Baseline for 0 params is 4, and the description correctly does not invent parameter details. It does not confuse the agent about arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns database health stats, listing specific metrics (row counts per table, schema version, DB size, FTS5 availability, embeddings status). This is a specific verb+resource combination that distinguishes it from sibling tools focused on tasks, graphs, and retrieval. The phrase 'verify the thinking_os database is operational' reinforces its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this tool to verify the thinking_os database is operational and to get a quick summary of stored data volume,' providing clear context on when to use it. It does not mention alternatives or exclusions, but for a health-check tool with no parameters, this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint: false, idempotentHint: false) already imply a non-read, non-idempotent operation, and the description's 'Record' aligns with this. The description adds a return-value note but does not disclose potential side effects, duplication behavior, or permission requirements beyond the basic write implication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an opening purpose statement, a labeled Args block, and a Returns block. Every sentence serves a purpose, and the format is scannable and front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and an output schema, the description gives comprehensive parameter semantics and return value information. It covers all required and optional fields with examples, making it fully adequate for an agent to invoke the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining every parameter with type, optionality, and examples. It explicitly enumerates valid outcome values (success, rework, partial, blocked), provides agent_type examples, and clarifies units for duration_ms, adding significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Record a single agent performance metric after task completion,' using a specific verb and resource with a clear trigger. This differentiates it from sibling tools like cos_metric_query and cos_metric_trend, which are for retrieval and trends.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'after task completion' provides a clear context for when to use this tool, establishing a usage trigger. However, it does not explicitly mention alternatives or when not to use it, such as pointing to cos_metric_query for reading metrics, so it misses explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent), it reveals it reads specific files (".coding-os/<agent>/sessions/*.json"), applies SSOT rules in board_os.presence, and defines behavior when agent is empty (reports all registered adapters). This adds valuable operational detail without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences: purpose, data source, empty-agent behavior, and usage context. No redundant phrasing; each sentence adds distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's single optional parameter and the presence of an output schema, the description sufficiently covers data provenance, rules applied, empty-agent semantics, and practical use. It doesn't enumerate all return fields, but that is handled by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description must compensate. It explains the empty-agent behavior ('every adapter registered... is reported') but does not explicitly define the expected format/identifier for a non-empty agent value. Thus, partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Return per-agent presence state and live-session inventory,' a specific verb+resource statement. It details the data source (.coding-os sessions files) and clearly differentiates from sibling tools by focusing on presence/session inventory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States it is used by cos daily, CI gates, and the live-agents board UI to verify zombie sessions are gone after deploy, giving concrete use cases. Does not explicitly name alternative tools or exclusion criteria, but the usage context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write (readOnlyHint=false), idempotent, and non-destructive. The description adds valuable context: 'forge auto-detected' and 'metadata only, never the id,' which clarifies the tool's effect without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It efficiently conveys the tool's purpose and key behavioral constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 simple parameters) and presence of an output schema, the description sufficiently covers the essential behavior. It could mention prerequisites but is otherwise complete for selecting and invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by giving semantic meaning to 'ref' via example and clarifying it is an external_ref. The 'task_id' param is self-explanatory from its name, so overall parameter semantics are adequately conveyed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Set a task's optional external_ref') with a concrete example (github#42), and it distinguishes this tool from siblings by emphasizing 'metadata only, never the id.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool ('Set a task's optional external_ref') and includes an exclusion ('never the id'), but it does not explicitly name alternative sibling tools like cos_task_edit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds meaningful behavioral context beyond annotations: describes BFS depth limit (max_hops) and auto-resolution of raw paths. The annotations already indicate read-only and idempotent behavior, so the description enriches that with algorithmic details, though failure behavior is not covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Highly concise: a one-sentence purpose followed by clear bullet-style parameter descriptions. Every line adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential aspects: purpose, parameter behavior, and algorithmic constraints. The output schema handles return details. Missing only explicit guidance on when to prefer this over sibling graph tools, but overall is complete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates by explaining all three parameters: source_uid and target_uid resolution rules, and max_hops as a BFS depth limit with default 5. This provides semantics the schema lacks entirely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Shortest path between two nodes (either direction)' with a specific verb and resource. It distinguishes from sibling graph tools like cos_graph_trace and cos_graph_search by focusing on the path computation and bidirectional nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use (finding shortest paths between two nodes), but does not explicitly state exclusions or direct alternatives to other tools. It references cos_graph_impact for the resolution scheme, which is a helpful pointer but not a usage alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by disclosing that results are heuristic ('Candidates only') and explicitly excluding shell scripts ('Shell excluded'), which is beyond what annotations provide. It does not discuss auth or rate limits, but these are less critical for a read-only query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args and Returns sections, front-loading the core purpose. Each sentence provides necessary information—purpose, limitations, parameter details, and return format—without redundancy. It is concise yet informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only graph analysis tool with an output schema, the description is nearly complete. It covers the purpose, parameters, return envelope, and the nuance of indirect exercise. It could mention whether any prerequisites exist (e.g., graph must be pre-built), but this is not essential for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining both parameters: 'kind: Optional filter — function | method | class. Empty = all three.' and 'top: Max returned (default 50, max 500).' This adds meaning beyond the bare schema field names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List prod function/method/class with zero inbound edge from any test (untested symbols).' This uses a specific verb ('List'), a specific resource (prod function/method/class), and a specific condition (zero inbound edge from any test), making it distinct from sibling graph tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context on when to use this tool by explaining that 'Candidates only: indirect exercise (CLI / fixtures / dynamic dispatch) may not appear as a graph edge. Shell excluded (no call-graph).' This clarifies the tool's limitations and interpretive caution. However, it does not explicitly contrast with alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond those hints: cold start behavior reads from skill-enforcement.md, warm behavior uses historical successful skills, and returns a JSON list. This is a meaningful supplement, though it does not cover all edge cases (e.g., error handling).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence summary, cold/warm behavior, a clearly labeled Args section, and a Returns section. No filler or redundancy; every sentence contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description appropriately includes return format. It covers cold/warm behavior, parameter details, and output structure. It is complete enough for an agent to invoke the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It explains domain with examples, task_type as optional with examples, and complexity as Cynefin classification with optionality. This is helpful, though the lack of an enumerated list for complexity and domain values leaves some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Recommend skills') and identifies the resource (skills based on historical outcome data). The cold/warm distinction adds behavioral scope, and the title 'Route Skill Recommendation' reinforces the purpose. It is well differentiated from sibling tools like cos_route_model by focusing on skill recommendation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when the tool is used: cold start returns static defaults, warm start augments with historical successes. It does not explicitly name alternatives or state when not to use it, but the behavior is described well enough for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, lowering the bar for safety disclosure. The description adds useful behavioral context: it returns only direct dependencies and describes the return structure (JSON with task_id, dependencies list, and count), going beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized, leading with the main purpose, followed by usage and behavioral notes, then clearly labeled Args and Returns sections. No unnecessary details or repetition are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only query tool with one parameter and an existing output schema, the description covers the essential aspects: when to use it, what it returns, how the parameter is formatted, and the direct-only limitation. No significant behavioral or usage gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for parameters is 0%, so the description must compensate. It does so by explaining that 'task_id' is a task identifier and providing a concrete example ('TASK-199'), which clarifies the expected input format well for a single-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Return the tasks that task_id directly depends on.' It clearly defines the tool's scope by noting it returns only direct (first-level) dependencies, which distinguishes it from related traversal or downstream-dependency tools like cos_task_dependents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'Use before starting a task to verify prerequisites are done.' It also provides guidance on handling transitive dependencies by recommending repeated calls, though it does not name alternative sibling tools such as cos_task_dependents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already indicate a write operation (readOnlyHint=false), the description adds valuable behavioral context: each call creates a new row linked to the previous via supersedes_id, implying an append-only chained structure. It also discloses the return payload (status, id, supersedes_id).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an intro, Args block, and Returns block. It is reasonably sized for 8 parameters and provides essential detail without fluff. Slightly verbose but acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 params, output schema exists), the description is thorough: it explains each parameter, the linking behavior, and the return format. It is complete enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It provides meaningful interpretations for each parameter, e.g., 'architectural_decisions: JSON array of {decision, rationale} objects' and 'confidence: Confidence in this trajectory assessment (0.0-1.0)'. This goes well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Persist') on a specific resource ('project trajectory snapshot') for the current session. It also distinguishes itself from the sibling tool 'cos_trajectory_read' by focusing on writing/persisting rather than reading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the purpose ('so future sessions have strategic context') and implicitly positions itself as the write counterpart to cos_trajectory_read. However, it does not explicitly state when not to use it or mention alternatives beyond the implied read tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotent, non-destructive), the description reveals the digest's size limit, rolling-content nature, and the fact that it can be truncated. It also sets expectations with the return envelope `{path, size_chars, truncated, status}`.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, then provides compact context, Args, and Returns sections. Every sentence contributes value with no repeated schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-param tool with an output schema, the description covers purpose, file location, content semantics, parameter behavior, and return shape. No meaningful gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates by explaining `project_root` means "Override project root" and that an empty/default value uses cwd. This is exactly the semantic information an agent needs beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: "Refresh `.coding-os/digest.md` from current memory state," which is precise and distinct from all sibling tools. It further explains what the digest contains, leaving no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the digest is read at session-startup to provide a memory anchor before retrieval, giving clear context for when regeneration is relevant. It does not explicitly name alternatives or exclusions, but no sibling tool competes with this digest-regeneration function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds beyond annotations by noting the migration v25 requirement and that 'domain' is reserved for future use. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet well-structured with separate paragraphs for purpose, usage, Args, and Returns. Every sentence adds value and no information is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and three parameters, the description covers purpose, usage timing, prerequisites, parameter semantics, and return format. It leaves no important gaps for selecting or invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides zero descriptive text (0% coverage), but the description compensates with a full Args section: explains 'root_cause' filter values, 'domain' reserved status, and 'limit' range/default. This fully clarifies parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Aggregate') and resource ('backtrack_events'), and clearly states the output (root_cause categories with examples). It distinguishes itself from sibling query tools by focusing on failure anatomy from backtrack events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use before planning to avoid known failure modes' and notes the prerequisite migration v25. It does not mention when not to use the tool or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context by noting that betweenness is expensive and that degree is the cheap default, plus describing the return envelope. There are no contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with a clear one-line summary followed by a terse usage context and parameter list. Every sentence adds value, and no redundant information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and all parameters explained, the description covers the essential semantics needed to invoke the tool correctly. It even notes the difference in computational cost between metrics, which is useful for selecting between degree and betweenness. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite a 0% schema description coverage, the description fully explains all three parameters: metric (with values and default), top (max nodes and default), and kind (with example and empty behavior). This compensates entirely for the missing schema annotations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Hub detection — surface high-degree (or high-betweenness) nodes', using a specific verb and resource. It clearly distinguishes this tool from sibling graph tools by focusing on centrality metrics, and it ties to concrete use cases (chokepoints, refactor priorities).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool ('Use to identify chokepoints / refactor priorities / nodes that demand extra review') and explains the trade-off between metric choices (cheap degree vs expensive betweenness). However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the read-only, idempotent safety profile. The description adds valuable behavioral context: the distinction between import cycles as a design smell and call cycles that may be legitimate, plus the exact return envelope structure. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and well-structured using Args/Returns sections. Every sentence contributes meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, parameter semantics, and return envelope, which is complete for a read-only graph query tool. The output schema exists, so detailed return field descriptions are not required, and none are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter: scope's two values, top as a cap on returned cycles, and min_size as a filter threshold. This is sufficient for correct parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Detect circular dependencies as strongly-connected components.' It clearly identifies the tool's function and distinguishes it from sibling graph tools by focusing on cycles/SCC analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for the scope parameter (imports vs calls) and explains what each represents, guiding when each mode is appropriate. However, it does not explicitly contrast with sibling graph tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds meaningful context: empty query = global PageRank, optional personalization, and the return format ('JSON envelope with nodes ranked'). This is sufficient beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line definition, a 'Use for' section, structured Args, and a Returns line. No redundant words or repeated schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity tool with 5 optional parameters and an existing output schema, the description covers purpose, all parameters, and return shape. The 'use for' section provides application context, making it complete for an agent to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero description coverage (all params are just names with defaults), so the description carries full burden. It explains all five parameters: query (personalisation, empty=global), top (max nodes), kind (filter), damping (PageRank damping factor), iterations (power-iteration count). This adds rich meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'PageRank — node importance, optionally personalised by query,' clearly identifying the tool as a node-importance ranking algorithm with personalization support. It distinguishes itself from sibling graph tools (e.g., cos_graph_centrality) by naming PageRank and listing concrete use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Three explicit use cases are given: knowledge condensation, query-personalised search ranking, and documentation sourcing. This provides clear context for when to use the tool, though it does not name alternatives or state when NOT to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds value by detailing what the plan covers (call-sites, docs, tests, strings) and mentions 'risk', giving extra context about the expected behavior beyond the annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the purpose, and uses a clean Args list. Every sentence contributes meaningful information with no redundancy. It is an example of efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description does not need to explain return values or safety. It covers the tool's purpose, all parameters, and the scope of the plan. This is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only field names with no descriptions (0% coverage). The description fully compensates by explaining each parameter: uid's scheme formats and auto-resolution, new_name as replacement symbol name, and check_strings as an option to scan string literals. This is crucial for correct invocation and well above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Plan a rename — call-sites, docs, tests, strings, risk.' This clearly states the tool's function with a specific verb and resource, and it uniquely identifies what the tool covers. It is not a tautology and distinguishes itself from sibling graph tools by focusing on rename planning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: when you need to plan a rename and assess its impact across call-sites, docs, tests, and strings. It does not explicitly name alternatives or provide exclusion criteria, but the context is clear enough for an agent to select it for rename planning. A small deduction for not mentioning when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavior details beyond annotations: it is a pure structured filter, results are sorted by task_id ASC, and the response includes a count. This goes beyond the minimal baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an opening summary, usage context, and labeled Args/Returns sections. Every sentence adds value, with no fluff. It is concise yet complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers all necessary aspects: params, defaults, valid values, output format, and sorting. The presence of an output schema means return details need not be over-explained, and the description fills the gap left by the absent schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining each parameter: status options (open/wip/done/blocked), domain examples, and limit range (1-100, default 20). It also clarifies that empty means 'all', which is critical for usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists tasks with optional status/domain filters, using the specific verb 'List'. It explicitly contrasts with semantic search by saying 'No semantic query — pure structured filter', distinguishing it from sibling tools like cos_task_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Use when you need "all open backend tasks" or "all blocked tasks" without a specific concept.' This implies a structured-filter use case and differentiates from semantic query. However, it does not name a specific alternative tool, so it is not as explicit as the high-calibration example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavior beyond annotations: it returns only direct dependents (non-transitive) and describes the return JSON structure with task_id, dependents list, and count. This adds useful context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: purpose statement, usage hint, and Args/Returns sections. Every sentence serves a purpose with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with an output schema, the description covers the use case, parameter semantics, returned data, and scope limitation (non-transitive). It is fully sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero per-parameter description coverage, but the description's Args section fully explains `task_id` with an example ('TASK-195') and clarifies it is a task identifier. This completely compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns tasks that declare `task_id` as a dependency, with a concrete example. It also specifies 'direct dependents — non-transitive', which distinguishes it from related tools like cos_task_dependencies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames the tool for impact analysis with a sample question, providing clear context for when to use it. It notes the non-transitive limitation but does not name an alternative for transitive dependents, so it lacks an explicit when-not/alternative clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and idempotent, but the description adds valuable context: the semantic search nature and the fallback to LIKE queries when embeddings are unavailable. This is beyond what annotations provide, though it omits details like error handling or sorting behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an Args list and Returns section, front-loading the semantic search purpose. Every sentence contributes value, and the length is appropriate for the detail provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description covers all necessary aspects: when to use, behavior, parameter meanings, and return structure. It is complete and self-contained, even listing result fields explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains each parameter (query with example, status with enum values, domain, and limit with range and default), making the tool exceptionally usable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Semantic search over the task store with optional status/domain filters' using a specific verb and resource. It distinguishes itself from sibling search tools by emphasizing semantic matching and fallback behavior, setting it apart from keyword-based search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this when you need to find tasks related to a concept — even when exact keywords don't match', providing clear context for when it applies. It doesn't explicitly name alternatives or exclusions, so it falls slightly short of the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context by listing the kind of content returned (phase, current focus, architectural decisions, anti-patterns, open questions) and by framing it as a session-start snapshot, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose, followed by a clear use case, then structured Args and Returns sections. Every sentence adds value and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description covers purpose, usage timing, parameter semantics, and return shape. The inclusion of the return JSON structure makes it self-sufficient even without the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'limit' as an integer with default 1; the description adds the accepted range (1-20) and clarifies that it controls the number of recent snapshots. This fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Return the most recent project trajectory snapshot(s)') and clearly defines the tool's scope. It also distinguishes itself from the task-board tools by stating it should be used to understand project direction before looking at the task board.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Use at session start to understand WHERE the project is heading before looking at the task board.' It does not mention when not to use the tool or name direct alternatives, but the context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and idempotent annotations, the description explains the spaced repetition mechanism (fading patterns with 0.2-0.4 confidence) and the return format, giving valuable insight into how results are prioritized. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: a clear one-sentence purpose, a single behavioral note, then a structured Args list and Returns. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with four optional parameters and an output schema, the description covers the purpose, behavioral details, parameter semantics, and return format. The only missing detail is a fuller definition of 'current task context', but that is likely implicit. It is complete enough for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero property descriptions, so the Args section is essential. It provides meaningful explanations for each parameter, including examples for domain and task_type and a range for limit. The complexity parameter could be more explicit about allowed values, but overall it compensates well for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns relevant patterns for the current task context, specifying the action and resource. It distinguishes itself from siblings like cos_learn_extract and cos_learn_validate by focusing on suggestion rather than extraction or validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by mentioning 'current task context' and the spaced repetition prioritization, indicating when to use it. However, it does not explicitly contrast with alternatives or state when not to use, preventing a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations. It explains that precision is derived from (was_cited, outcome) pairs, counts cited-success as 1.0 and cited-rework as 0.0, and frames it as 'honest.' This discloses the computation logic and the meaning of the metric, which is very valuable for correct interpretation. It is consistent with the read-only and idempotent hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a concise explanation of how precision is calculated, a use-case statement, and clearly separated Args/Returns sections. It is front-loaded and every sentence adds useful information without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, metric derivation, use case, parameters, and returns structure. However, it mentions 'below_gate' and 'gate' in the return without explaining what gate threshold is or how it is set. Since an output schema exists, this is a minor gap, so a 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 0%, the description's Args section clearly explains each parameter: lookback_days as 'Window in days (default 14)' and layer as an optional filter with allowed values ('memory'|'docs'|'tasks'). This fully compensates for the lack of schema descriptions and adds default values and allowed domains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Report mean retrieval precision over the lookback window.' It goes on to define precision clearly from (was_cited, outcome) pairs, and the intent is distinct from sibling retrieval tools like cos_retrieval_cite or cos_retrieval_learn, which handle citations and learning rather than quality reporting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when this tool is valuable: 'Used to decide whether contextual enrichment is worth the LLM cost.' This provides a clear decision context, though it does not explicitly mention alternative tools or when not to use it, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it explains the stage-1 metadata pre-filter, how auto_context soft-defaults domain from the active task's swimlane, and that filter_hints are heuristic suggestions never auto-applied. It also discloses the two-stage search process and response meta fields. This goes far beyond the readOnly/idempotent annotations and provides rich behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although lengthy, the description is well-structured and every sentence earns its place. It front-loads the core purpose, then systematically explains the pre-filter logic, parameters, and response meta. For a 9-parameter tool with no schema documentation, this level of detail is necessary and appropriately organized with an Args section and clear examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for the tool's complexity. It covers parameter semantics, behavioral edge cases (e.g., stale docs, superseded specs), response format (JSON envelope with listed fields), and the decision-making flow for filter hints. The presence of an output schema does not negate the need for this semantic richness, and the description delivers it fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter (query, source_types, limit, mode, domain, layer, since_iso, include_inactive, auto_context) with examples, defaults, and behavioral nuances. For instance, it clarifies that 'domain' is 'Indexed' and 'include_inactive' hides chunks marked is_active=0. This is a model of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'Semantic + lexical search over project documentation chunks.' It specifies the resource (project documentation) and distinguishes itself from generic search tools like cos_search by emphasizing metadata pre-filtering and stage-1 filtering. The title 'Search Project Documentation' reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, including a mental model ('Filter → Search → Summarize') and specific guidance for parameters like since_iso ('Use when the agent asks about recent or current state') and include_inactive ('Set True for decision-history retrieval'). It does not explicitly name alternative tools or exclusions, but the usage context is well implied for a documentation search tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds significant behavioral context beyond that: include_content reads source text capped at 2000 chars with a truncation flag, is silently skipped if file missing; include_evidence costs ~2× tokens; include_spine pulls the CONTAINS-ancestor chain. These details are not inferable from annotations and help the agent anticipate side effects and costs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence purpose, then organizes parameters in a clear Args block. The formatting is tight, using code spans and concise explanations. No fluff; every sentence adds technical detail. The length is justified by the number of parameters and the complexity of the UID scheme.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, UID resolution, optional content/evidence/spine) and the presence of an output schema, the description is highly complete. It covers param behavior, edge cases (missing file, fuzzy match), cost implications, and workflow (run cos_graph_query first). The output schema obviates the need to describe return structure, so the description correctly focuses on inputs and side behaviors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It compensates thoroughly: uid_or_name is explained with a complete UID scheme, examples, auto-resolution rules, and fallback; direction lists values; depth explains BFS; include_content and include_evidence describe concrete effects; include_spine explains what it pulls. Every parameter is semantically enriched beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific, action-oriented statement: 'Return callers + callees + siblings + referenced docs around a symbol.' This clearly identifies the resource (a symbol in the code graph) and the scope (callers, callees, siblings, referenced docs), distinguishing it from sibling tools like cos_graph_query (which discovers candidates) and cos_graph_references (likely narrower).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit workflow guidance: 'Run cos_graph_query first to discover candidates.' This tells the agent when to use this tool relative to a direct alternative. It also clarifies the auto-resolution and fuzzy fallback behavior for uid_or_name. However, it does not explicitly contrast with other graph tools (e.g., cos_graph_trace, cos_graph_impact), so there is still some ambiguity about when to choose this over those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety profile is covered. The description adds valuable behavioral nuance: it defines what counts as a reference, notes that results are candidates (not authoritative), and explains the include_tests flag alters edge counting. This exceeds mere scope scouting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear topic sentence, a caveat paragraph, and labeled Args/Returns sections. Every sentence adds value: the purpose, the nuance about candidates, parameter semantics, and return envelope info. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate tool complexity, 0% schema coverage, and no param enums, the description fully compensates: all three parameters are defined, the return format is mentioned, and critical caveats about false positives are included. The existence of an output schema further reduces burden, making this highly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full parameter burden. It explains `kind` as a filter (function|method|class, empty=all three), `top` with default 50 and max 500, and `include_tests` as 'Count test-sourced edges + include test files'. This adds meaning far beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'List in-repo symbols with zero non-test inbound references' and clarifies it as 'dead-code candidates'. It further distinguishes itself from siblings by noting it is 'the inverse of centrality', immediately separating it from related graph tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns that results are 'Candidates only' and that dynamic-dispatch/CLI-registered/externally-called symbols may appear, advising to 'verify with cos_graph_references before deleting'. This names the alternative tool and provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint). The description adds valuable behavioral context: raw repo paths are auto-resolved, the default 'kinds' behavior selects specific edge types per node kind, and the limit parameter caps results. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line purpose, followed by a well-organized Args section. Each parameter's documentation is dense but relevant. The 'R4-02' reference is a minor distraction but does not detract from overall structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a graph tool with complex uid schemes and edge type selection, the description comprehensively covers required parameters, default behaviors, and parameter interactions. An output schema exists, so return structure is already specified and need not be repeated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It thoroughly explains each parameter: uid with a detailed scheme and examples, kinds with comma-separated edge types and per-node-kind defaults, and limit with a default value. This fully compensates for the lack of schema-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List inbound edges — "who references this?"'. This clearly defines the tool's function and distinguishes it from sibling graph tools like cos_graph_trace or cos_graph_impact, which focus on other aspects of graph traversal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context is given: this tool is for finding who references a given node. It also explains that an empty 'kinds' parameter automatically selects appropriate edge types per node kind, offering concrete usage guidance. However, it does not explicitly mention alternatives or scenarios where another tool should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety behavior is covered. The description adds meaningful behavioral context beyond annotations: it explains the search strategy (semantic + lexical + centrality) and the constrained range for top_k. It does not describe return format or pagination, but the output schema covers return structure, so no significant gap remains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single purpose statement, one alternative-direction sentence, and two terse parameter explanations. Every sentence earns its place, and the most important information (what it does) is front-loaded. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (two params, output schema present, generous sibling context), the description covers purpose, usage boundaries, parameter semantics, and relationships to alternatives. The output schema handles return-value documentation. The description is complete for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
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 does so thoroughly: 'query' is explained as 'Natural-language or code-ish query' with an example, and 'top_k' is given a numeric range (1–50) that is not present in the schema. This adds real semantic value beyond the bare type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Find') and resource ('code symbols'), and clearly indicates the input type (natural-language description) and approach (semantic + lexical + centrality). It also distinguishes itself from the sibling tool cos_graph_query by explicitly scoping to natural-language searches, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit usage guideline: 'For a KNOWN name / path / uid, use cos_graph_query instead.' This clearly tells when NOT to use this tool and points to the correct alternative. This is exactly the kind of guidance that helps an agent select correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only indicate readOnlyHint=false), the description details the behavioral mechanics: it updates confidence using 'brain-inspired formulas' with specifics like LTP diminishing returns and LTD proportional penalties. It also discloses the return value (JSON with old/new confidence and validation status). This adds rich context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: a single-sentence purpose, a compact bullet list for formulas, followed by Args and Returns sections. Every sentence earns its place, and the main action is front-loaded. It is neither bloated nor under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple two-parameter tool with an output schema (has output schema: true), the description is complete. It covers purpose, behavioral nuance, parameter semantics, and return format. There is no missing critical information for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully carries parameter meaning. It explains pattern_id as 'ID in learned_patterns table' and was_helpful as 'Whether the pattern was useful (default True).' This is precise and adds meaning beyond the bare type/default in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific action: 'Record whether a suggested pattern was helpful.' This distinct verb-resource pair unambiguously states the tool's function and distinguishes it from siblings like cos_learn_suggest (which suggests) and cos_learn_extract (which extracts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clearly implied: this is for providing feedback on a suggested pattern, whether it was helpful or not. However, it does not explicitly name alternatives (e.g., 'use cos_learn_suggest to generate suggestions') or state when not to use it. This is clear context without explicit exclusions, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant context beyond the annotations: it explains the consequence ('Cited retrievals get ~4× the weight when priority-learning runs'), warns about signal integrity, and describes the exact return format (`{updated, unknown}`). This goes well beyond the idempotent/readOnly hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, when to call, args, returns). Every sentence contributes meaningful information, and it is front-loaded with the primary action. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers the essential context: the purpose, the trigger condition, the parameter semantics, and the return shape. It is complete enough for an agent to invoke the tool correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a bare string type with 0% description coverage, but the description fully compensates. It explains the parameter format (comma-separated ints), the source of the IDs (prior responses from specific search tools), provides an example, and clarifies the meaning of the `unknown` return list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Mark retrieval rows as actively cited by the agent.' This clearly states the tool's function and differentiates it from siblings like cos_retrieval_learn and cos_retrieval_quality by focusing on the act of citing after meaningful use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('Call this after using one or more chunks/patterns/tasks in a meaningful way') and a clear when-not-to-use exclusion ('do NOT cite passive retrievals'). However, it does not name alternative tools for other scenarios, so it misses the 'alternatives' component for a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare readOnly, idempotent, and non-destructive behavior, the description adds crucial context: 'The underlying LLM enrichment path is intentionally a stub.' This reveals that the tool does not perform enrichment itself but only recommends, and it surfaces the cost-warning aspect, which are non-obvious behavioral traits beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with a clear opening purpose, a brief rationale, and formatted Args/Returns sections. Every sentence adds value, and the structure makes key information (purpose, stub behavior, parameter, output) immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and a simple recommendation output, the description covers all essential context: what it does, why it exists, what input it takes, and what it returns. The output schema is present, and the explicit Returns block further clarifies the response shape, including the optional cost_warning field.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, lookback_days, has no description in the schema (0% coverage). The description compensates fully by defining it as 'Window of retrieval quality data (default 14),' giving the parameter clear meaning and default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Recommend whether to enable contextual retrieval enrichment.' This clearly distinguishes it from sibling retrieval tools like cos_retrieval_quality or cos_retrieval_cite, which likely focus on measuring or citing retrieved content rather than making a cost-aware recommendation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains this tool is used to make a metric-driven decision before 'anyone pays the Haiku bill,' giving clear context for when to invoke it—as a gate before enabling enrichment. It does not explicitly name alternatives or exclusions, but the purpose and timing are unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by detailing the exact priority adjustment rules, clamping bounds, and the dry_run behavior that avoids writes while still computing changes. It also explains the weaker signal for passive retrievals and the return envelope, providing comprehensive behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a summary line, bullet points for update rules, a clamping note, a usage intent sentence, and clearly labeled Args/Returns sections. It is detailed but every line adds necessary information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity of a learning/adjustment tool with an output schema, the description fully covers behavior, parameters, return shape, and intended execution context. It is self-sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 0%, the description includes an Args section that fully explains both parameters: lookback_days (what it controls, default) and dry_run (what it does, including the 'without writing' behavior). This compensates entirely for the schema's lack of description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Adjust document_chunks.priority based on recent retrieval outcomes.' It clearly differentiates this tool from siblings like cos_retrieval_quality or cos_retrieval_cite by focusing on priority modification from outcome learning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is 'Intended to run nightly via cron or after a batch of task-done events,' giving explicit context for when to use it. It does not explicitly name alternative tools or exclusions, but the scheduling context is clear and practical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: BFS-based traversal (depth and visit_limit), edge filtering by confidence_min, and the risk-tier grouping output. It also explains the truncation signal (meta.walk_truncated) that indicates when to increase limits. This goes beyond annotation information without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose that front-loads the core function, followed by a compact Args block. All parameter explanations are precise and useful, with no filler or redundancy. The format makes it easy to scan and locate key details like uid schemes and defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, graph traversal, risk tiers), the description is comprehensive. It covers every parameter with examples and edge cases, references a sibling tool for uid discovery, explains default behavior (confidence_min 0.3, visit_limit 500), and describes the risk-tier output. The presence of an output schema means return-format details are not needed from the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only parameter names and defaults (0% coverage), but the description fully documents each parameter in the Args block. uid includes a detailed scheme with examples and auto-resolution behavior; direction explains downstream vs upstream semantics; depth is defined as a BFS hop limit; confidence_min is tied to edge scores; visit_limit is clarified as a node-visit cap with a tuning hint. This far exceeds schema-level information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Group affected nodes by risk tier') and names the concrete outcome categories (will_break / should_review / context). This clearly distinguishes it from sibling graph tools like cos_graph_query or cos_graph_trace, which focus on traversal or search rather than impact classification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises running cos_graph_query first when unsure about the uid, naming a direct alternative. It also explains how to choose direction ('downstream (callers — break if uid changes)' vs 'upstream (deps uid calls/imports)') and provides a practical hint to raise visit_limit when meta.walk_truncated is true. This is actionable guidance for selecting and tuning the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent, non-destructive), the description discloses that the tool performs lexical + graph expansion, falls back to direct uid lookup when lexical pass returns nothing, and returns weaker matches for long natural-language queries due to index limitations. This adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with purpose, alternative, tip, UID scheme, fallback behavior, and args. Although long, each section serves a distinct purpose and no sentence is wasted; the 'S3' typo is a minor blemish but doesn't detract.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-param tool with output schema, the description covers query semantics, UID formats, fallback behavior, parameter meanings, and return envelope. It also references external docs for deeper details. This is adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description's Args section fully specifies all 6 parameters with types, examples (e.g., kinds comma-separated), and behavioral notes (e.g., NL queries degrade). This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up symbols by a KNOWN short term, path, or uid, with a specific verb and resource. It explicitly distinguishes itself from cos_graph_search, which handles natural-language descriptions. The UID scheme adds further precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (known term/path/uid) and when not to (natural-language descriptions, use cos_graph_search instead). It also provides a TIP about preferring short terms and explains the trade-off with long NL queries. This is clear when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description enriches behavioral understanding by disclosing the exact fallback resolution sequence (direct uid → path/qualname → FTS5 → LIKE) and the return envelope with a 'strategy' field, which is beyond structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, usage, UID scheme, args, and return value. Every sentence contributes necessary information—no filler—while the front-loaded first line immediately conveys the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple UID formats, fuzzy resolution) and the absence of parameter descriptions in the schema, the description is remarkably complete. It covers the UID scheme, resolution order, all arguments, and return format, leaving no critical gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining each parameter's meaning and valid inputs. It details 'q' as natural language, label, path, or qualname; 'kinds' as a comma-separated filter; and 'top' with max results and default. This is essential given the minimal schema metadata.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Resolve a natural-language label, path, or partial uid to canonical uids.' This clearly states the tool's purpose and differentiates it from siblings by positioning it as the UID resolver to use before other cos_graph_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this BEFORE other cos_graph_* tools when you don't know the exact uid.' It also details the resolution strategy order, adding practical guidance on how the tool handles different query types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations being present, the description adds significant behavioral context: 'Read-only over memory rows: retrieval telemetry only' and details about the pre-filter (min_confidence, since_days) and their effect on ranking. It also explains that the tool does not modify confidence, which is beyond what annotations convey. No contradiction with annotations; the readOnlyHint=false is reconciled by the telemetry side-effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence carries value. It is well-structured with clear sections (intro, usage, stage-1 pre-filter, Args, Returns) and is front-loaded with the core purpose. No fluff or repetition beyond reinforcing important distinctions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no schema-level descriptions, and an output schema, the description covers everything needed: parameter semantics, use case, behavioral constraints, and return format. It even explains the staging of filtering and the reason for default values, making it fully self-contained for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description fully compensates with an 'Args:' section that explains every parameter, including defaults, valid ranges, and behavioral implications. For example, 'min_confidence: Drop learned_patterns with confidence below this value (0.0-1.0). Default 0.3 (skips decayed noise).' This adds meaning far beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Search observations and learned patterns with 5-signal ranking.' This clearly distinguishes the tool from siblings like cos_doc_search or cos_graph_search by focusing on observations and learned patterns. The reference to the 'Orient step' further contextualizes its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Use during Orient step to find relevant past experience.' It also differentiates itself from related tools: 'Neither this tool nor cos_details moves confidence — only cos_learn_validate does.' This gives the agent a clear decision rule for when to rely on this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![coding-os MCP server](https://glama.ai/mcp/servers/kouroshez/coding-os/badges/card.svg)](https://glama.ai/mcp/servers/kouroshez/coding-os)

Score Badge

Copy to your README.md:

[![coding-os MCP server](https://glama.ai/mcp/servers/kouroshez/coding-os/badges/score.svg)](https://glama.ai/mcp/servers/kouroshez/coding-os)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kouroshez/coding-os'

If you have feedback or need assistance with the MCP directory API, please join our Discord server