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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds cost/latency context ('Cheap single-question-batch call'), which is genuine value beyond annotations, but there is no output schema and no description of what the classification returns (boolean flags, labels, confidence), leaving a real gap for a classification tool.

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

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

Two tightly written sentences with the purpose front-loaded and the enumerated categories doing useful work. 'Cheap single-question-batch call' is slightly cryptic and could be clearer about batching semantics, which is the only real flaw.

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

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

For a single-parameter, read-only classification tool the description is largely sufficient: the enumerated categories effectively disclose the expected output dimensions even without an output schema. The missing piece is how that classification is returned and consumed, plus the unresolved meaning of 'batch.'

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

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

Only one parameter and schema coverage is 100%, with the schema already stating 'The user task to classify.' The description adds only the notion of a 'single-question-batch call,' which is ambiguous about whether one or many queries may be supplied. Baseline 3 is appropriate since the schema carries the parameter burden.

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

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

States a specific verb ('Classify') and the exact dimensions being classified (current information, documentation, repository access, files, computation, database, browser, literature), so the agent knows precisely what the call produces conceptually. It does not name the sibling it feeds into (systemone_decide_tools) explicitly, so sibling differentiation is implied rather than stated, keeping it below a 5.

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

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

'before deciding on tools' gives a clear workflow position: this is the pre-step that precedes tool selection. There are no explicit exclusions or named alternatives, so an agent infers rather than is told which sibling to call afterward.

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

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

The description usefully discloses the return contents (utilisation, missed recommendations, unexpected tools) and the key limitation that cross-server calls are invisible. However, annotations declare readOnlyHint=false, so the call has side effects, and the description never says what is written or stored during the audit — a notable gap for a non-read-only tool.

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

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

Three short sentences, front-loaded with the comparison action, then the outputs, then the one operational caveat. Every sentence carries information the agent needs.

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

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

For a four-parameter tool with no output schema, the description covers the action, the returned artefacts, and the key input constraint. Missing only side-effect disclosure for the non-read-only annotation and any hint about the nested priorities parameter.

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

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

It explains why executed_tools is mandatory and implies recommended_tools can be omitted in favour of stored recommendations, which adds real meaning beyond the schema. It says nothing about the nested priorities object or about how task_id ties to systemone_decide_tools beyond what the schema already documents; with 75% schema coverage, this is baseline-level.

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

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

States a specific verb and resource: compares recommended tools against reported executed tools and returns utilisation, missed recommendations, and unexpected tools. This clearly separates it from siblings like systemone_decide_tools or systemone_recommend_skills, though it never names the alternative explicitly.

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

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

Usage is implied as a post-execution audit step and the description gives one hard constraint (the execution list must be supplied because the server cannot observe other MCP servers). It does not say when to prefer this over evaluate_result or what prerequisite call produces the task_id in prose, so guidance is adequate but incomplete.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered without the description. Beyond that, the description adds only the idea of a threshold comparison; it does not explain the scoring scale, what happens when options is omitted (is there a default threshold?), or what the verdict looks like. Useful context, but thin for a decision tool with no output schema.

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

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

Two tight sentences, front-loaded with the action and followed by the usage trigger. No filler, though a single added clause about the threshold or return value would have cost nothing and closed real gaps.

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

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

There is no output schema and the description does not describe the response beyond "whether it clears its threshold" — the score itself, its range, and any explanation field remain unknown. Combined with the undocumented user_query and options parameters, an agent still has to guess at core call semantics for what is a three-parameter, nested-object tool.

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

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

Schema coverage is 33%: only tool_id is documented in the schema, while user_query and the nested options.threshold have no descriptions. The description hints at a threshold but never says what it is applied to, how it defaults, or what user_query should contain (a raw user utterance? a summarized task?). With low coverage the description needed to compensate and largely does not.

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

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

The description names a specific verb and resource ("Score a single tool against a task") and states the output shape in prose ("say whether it clears its threshold"). The word "single" implicitly contrasts with the batch-oriented sibling systemone_decide_tools, but it never names any sibling, so the differentiation is suggestive rather than explicit.

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

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

It gives a usable trigger condition: use when the agent is unsure whether one specific MCP tool is worth calling. That is a clear positive case, but there is no when-not guidance and no mention of the alternative (systemone_decide_tools / systemone_get_catalog) for tasks involving multiple tools.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavior beyond that: the response contains scores, priority tiers, and 'deterministic reasons', and an empty recommendation set is a valid outcome. It omits how discovery interacts with the available_mcp_servers override, but the core behavior an agent needs to decide is disclosed.

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

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

Three short sentences, front-loaded with the action and followed by the call trigger and the empty-result caveat. No filler, though the output-shape sentence could be trimmed since it partly restates the name.

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

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

There is no output schema, and the description only partially compensates by naming the return fields. With nested, sparsely documented parameters and a routing role that overlaps several siblings, an agent still lacks guidance on context/options usage and on how this differs operationally from check_tool_need.

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

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

Schema description coverage is only 33% and the schema is nested (context.project_type, context.working_directory, options.threshold, options.max_recommendations), yet the description never mentions context or options at all. Only user_query is effectively covered, via the schema's own 'The user task to route' and the phrase 'Analyse a user task', leaving the tunable threshold and recommendation cap unexplained in both places.

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

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

States a specific verb ('recommend') and resource ('available MCP tools') and describes the output shape (scores, priority tiers, deterministic reasons), which separates it from catalog/audit siblings. It does not name which sibling to prefer over systemone_check_tool_need or systemone_analyze_task, so the differentiation is inferable rather than explicit.

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

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

'Call this before complex or multi-step tasks' gives a clear trigger condition, and 'Returns no recommendations when the task needs no external tool' tells the agent the negative case exists. It stops short of naming alternatives for simple single-tool tasks, so the exclusion is implied rather than stated.

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

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

The description adds one genuinely non-obvious rule beyond the annotations: task success is never inferred from tool calls alone, only from a user-supplied outcome. That meaningfully shapes how the agent should populate the outcome argument. However, annotations declare readOnlyHint=false, implying the call has side effects, and the description says nothing about what is written or returned; combined with no output schema, the behavioral picture is incomplete.

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

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

Two tight sentences with the evaluative intent front-loaded and the key constraint second. No padding or redundancy. It is efficient, but efficiency is not offsetting for the missing detail elsewhere.

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

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

For a six-parameter tool with no output schema and low schema coverage, the definition says far too little: the return shape of the 'metrics', the relationship between executed and recommended tools, and any side effects are all unstated. The one rule it does state is valuable, but a large share of what an agent needs to call this correctly is absent.

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

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

Schema description coverage is only 33% — task_id, executed_tools, recommended_tools, and user_reported_outcome carry no schema descriptions. The description partially clarifies the outcome parameter's semantics (success requires a user-supplied outcome), but says nothing about what executed_tools versus recommended_tools mean or how they should be formatted. With such a large coverage gap, the description should compensate and does not.

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

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

The description gives a verb and object ("Report objective tool-usage metrics"), but "metrics" and "explicit limitations" are vague about what is actually produced or evaluated. It does not distinguish this from sibling tools such as systemone_audit_execution or systemone_analyze_task, which sound closely related. The title helps somewhat, but an agent reading only the description would be unsure how this differs from an execution audit.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives among the seven sibling tools. The statement about success only being reported when the user supplied an outcome is a behavioral rule, not a usage trigger. The agent must infer that this tool is for post-execution evaluation.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful disclosure about what the response contains and that config sources are surfaced, but says nothing about size, caching, or whether the catalog can be stale relative to refresh_catalog.

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

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

A single front-loaded sentence naming the return contents, followed by one short clause on purpose. Nothing is redundant and nothing could be cut without losing information.

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

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

With four optional parameters, no output schema, and a read-only annotation set, the description does the main remaining job: it tells the agent what the result contains. Only the category filter's purpose is left unexplained, which is a minor omission for a diagnostic tool.

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

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

Schema coverage is only 50%, but the parameters are self-describing: 'type' and 'availability' are closed enums whose values convey their own meaning, and the two prose-documented fields already carry defaults in the schema. The description's mention of 'resolved availability' reinforces the availability enum, so the remaining gap (category's semantics) is narrow rather than disqualifying.

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

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

States a concrete verb and resource ('Return the tool catalog') and enumerates what the payload contains: resolved availability, the skill index, and the config sources read. That is far more specific than its sibling systemone_refresh_catalog, though the description never explicitly contrasts the two.

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

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

Provides one implied use case ('explaining why a tool was not recommended'), which is genuine context for when to reach for it. It gives no exclusions and never names the obvious alternative (systemone_refresh_catalog, which presumably rebuilds rather than reads the catalog), so the agent must infer the boundary.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds real context beyond them: only metadata is read, never the skill body, which tells the agent the call is cheap and avoids side effects on skill content. It also discloses the return payload shape (path plus reason). It stops short of explaining ranking/threshold behavior or what happens when nothing clears the bar.

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

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

Three short sentences, front-loaded with the action and result, with each sentence adding a distinct fact (what it does, what it reads, what the caller must still do). No filler or repetition.

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

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

For a read-only ranking tool with a nested options object and no output schema, the definition covers purpose and read scope but leaves the tuning parameters unexplained and gives no sense of result ordering count or empty-result behavior. Adequate, but an agent would still be guessing about threshold semantics.

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

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

Schema coverage is 67%, so the description's baseline is a 3. It reinforces that ranking happens "against a task" (pointing at user_query) and that recommendations are drawn from skills "discovered on disk," which loosely frames available_skills as a restriction. It says nothing about the nested threshold or max_recommendations options, which are the least documented parameters.

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

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

"Rank the skills discovered on disk against a task and return the ones worth loading" names a specific verb (rank), the resource (discovered skills), and the matching criterion (a task), plus what comes back (SKILL.md path and reason). It is clearly distinguishable from siblings like systemone_get_catalog or systemone_refresh_catalog, which manage rather than rank the catalog.

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

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

"The agent still loads the skill itself" implies the two-step workflow: recommend here, then load separately, which is useful guidance. However, there is no statement of when to prefer this over systemone_analyze_task or systemone_decide_tools, and no exclusion or precondition guidance.

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

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

Annotations only supply readOnlyHint=false and openWorldHint=false, leaving the mutation profile ambiguous. The description fills that gap by stating explicitly that it never writes OpenCode configuration and never overwrites user-written catalog metadata, which tells the agent what state is and is not at risk. It stops short of saying whether the rebuilt catalog replaces cached data or whether a refresh can fail mid-way.

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

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

Two sentences, zero filler. The positive scope (what is re-read) comes first and the safety guarantees follow, which is the right ordering for a refresh operation.

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

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

For a parameterless, non-open-world tool with no output schema, the description covers what is refreshed and what is protected, which is most of what an agent needs. The remaining gap is the absence of any trigger condition or mention of what the refreshed state looks like on return.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level meaning is missing because no parameter exists.

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

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

The description names a specific verb ("Re-read") and enumerates the exact resources refreshed: OpenCode MCP configuration, tool catalog, settings, and skill index. That is far more precise than the title "Refresh discovery," though it never distinguishes this operation from the sibling systemone_get_catalog, which an agent could easily confuse it with.

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

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

There is no statement of when to call this tool, when not to, or which sibling to use instead. The clause about not writing configuration is a scope guarantee, not usage guidance, so an agent must infer the trigger condition (e.g. after config changes) entirely on its own.

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