mzizi-mcp

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

Although annotations already cover readOnly/idempotent/non-destructive, the description adds substantial context the annotations cannot express: the sandbox is documentation-backed only, nothing touches the user's machine or network, calls are STATELESS with the working directory resetting to `/`, output is truncated at 30KB, and only a fixed command set is available.

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

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

The description is long but heavily front-loaded and organized into purpose, reading model, path discovery, workflow, supported commands, statelessness, and examples. Some sentences restate the sandbox point ('nothing runs on the user's computer, the server host, or any network'), which is mild padding.

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

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

With no output schema, the description carries the return-value burden and does so: 30KB truncation, preference for `rg -C`/`head -N` over broad `cat`, and the instruction to convert `.mdx` filesystem paths back to URL paths in the final answer.

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

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

There is a single parameter and schema coverage is 100%, so the schema already documents `command`. The description nonetheless adds real calling semantics beyond the schema — command chaining with `&&`, absolute paths as the stateless-CWD workaround, `--help` discovery, and batching reads into one call.

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 (query) and resource (a virtualized, in-memory documentation filesystem rooted at `/`) and explicitly distinguishes itself from the sibling docs_search_mzizi. It even resolves the natural confusion that there is no separate 'get page' tool and that reading pages is done via `head`/`cat` on `.mdx` paths.

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 an explicit routing rule: start with the search tool for broad/conceptual queries, use this tool for exact keyword/regex matching, structural exploration, or full-page reads. It also states the recovery behavior when a path guess fails (`rg -il` instead of concluding the topic is undocumented).

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description correctly focuses on behavior the annotations cannot express: the return shape (contextual content with titles and direct links) and the concrete read path via the .mdx extension. It stops short of disclosing ranking, result limits, or empty-result behavior, which keeps it below a 5.

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?

Front-loaded with purpose, then usage, then return format, then the follow-up workflow. Every sentence carries information, though the parenthetical example ('head -200 /some/page.mdx') is on the verbose side for a description that will be read repeatedly.

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

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

With no output schema, the description takes on the burden of describing return values and does so (titles plus direct links). Combined with the explicit escalation path to docs_query_docs_filesystem for full content, an agent has everything needed to search and then materialize a page.

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

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

There is a single parameter and schema description coverage is 100%, so the schema already documents 'query' fully. The description never clarifies whether the query should be natural language, keywords, or a path fragment, so it adds no meaning beyond the structured field. Baseline 3 applies.

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 scoped to the Mzizi knowledge base and enumerates what it surfaces (information, code examples, API references, guides). It is clearly distinguishable from the sibling docs_query_docs_filesystem_mzizi, which it explicitly positions as the follow-up reader rather than a search.

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

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

Provides explicit when-to-use triggers ('answer questions about Mzizi', 'find specific documentation', 'understand how features work') and an explicit handoff condition: if you need full page content, use docs_query_docs_filesystem instead. The agent is routed to the correct sibling without inference.

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 the operation profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false, idempotentHint=false), and the description adds only the outcome ('so the docs team can fix it'). It says nothing about authentication requirements, whether submissions are anonymous/tracked, or expected turnaround, so added context is limited.

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

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

Three tight sentences: the domain-scoped purpose, the use case, and the exclusions. It is front-loaded and every sentence earns its place with no redundancy.

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

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

For a simple two-parameter submission tool with no output schema, the description covers purpose, triggers, and exclusions, which is all an agent needs to call it correctly. No return-value explanation is required since none exists.

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

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

Schema description coverage is 100%, so both parameters (path, feedback) are already well documented in the schema, including the path format convention. The description names no parameter-level details (e.g., accepted path formats) beyond what the schema provides, so the baseline 3 applies.

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 (report) and resource (a problem with the documentation site) with clear scope, noting it goes to the docs team. It also distinguishes itself from similar sibling actions by excluding product support and tool/assistant feedback, so an agent can tell it apart from mzizi_report_issue without opening either schema.

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

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

Explicitly lists when to use it (page is incorrect, outdated, confusing, incomplete, or has a broken example) and when not to use it (product support requests, feedback about this tool or assistant). Both the trigger and the exclusions are stated, leaving nothing to inference.

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, openWorldHint=false and idempotentHint, so the safety profile is covered. The description adds that computation is local with no network or upstream dependency, which reinforces rather than contradicts the annotations, but it says nothing about output shape, pass/fail semantics, or error behaviour on malformed colour values.

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 short sentences, front-loaded with the substantive capability and followed by the locality caveat. No filler, no restatement of the tool name or title. Every clause earns its place.

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

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

For a simple two-parameter read tool whose annotations and schema are both rich, the description covers purpose adequately. However, with no output schema present, the description leaves the return value completely unexplained — an agent does not know whether it receives a boolean, a ratio, a list of violations, or a threshold verdict.

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

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

Schema description coverage is 100%: both foreground and background carry '#RRGGBB' format documentation and both are required. The description adds no further parameter meaning, so the baseline 3 applies. The only implicit addition is that the two colours are contrasted against each other, which the parameter names already imply.

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 concrete resource (contrast and colour-vision) and a concrete threshold (the Mzizi APCA/AAA floor), so the resource is unambiguous. It stops short of a crisp verb+object statement like 'check foreground against background' and there is no sibling in the list that performs similar work, so no differentiation is needed or provided.

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

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

The description gives no when-to-use guidance, no prerequisites, and no comparison to any alternative. The only contextual statement is about execution locality, which is not usage guidance. An agent cannot infer from the text when this check is the right call versus any other evaluation step.

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 declare write/destructive/openWorld/non-idempotent, so the safety profile is already known; the description adds genuine context beyond that: submit is fire-and-forget ('returns a task id immediately and never waits for the run') and it requires Mzizi console sign-in. It stops short of explaining cancel semantics or what gets destroyed, so it's not a 5.

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

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

Three sentences, front-loaded with purpose, then the submit-and-poll behavior, then the auth requirement. No filler; every clause carries 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?

For an async task-delegation tool with no output schema, the description covers purpose, polling model, and auth. It leaves minor gaps around cancel semantics and the shape of a status response, but nothing that blocks correct invocation.

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 75% with descriptions for skill, taskId, and instruction; the enum for action is self-explanatory. The description reinforces async semantics for the submit action but adds little syntactic detail beyond what the schema already supplies, so baseline 3 is right.

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: 'Delegate a task to the fundi agent, or check on one.' It names the two operating modes and is easily distinguished from the sibling docs/read tools. An agent can tell what this tool does without opening the schema.

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 implies usage via the submit/task-status split and the asynchrony note, but never names alternatives or when-not to use it among the many mzizi_* siblings. Usage is inferable rather than explicit.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true and closed-world access, so the safety profile is covered. The description adds two pieces of context beyond that: results carry 'live counts' (freshness) and single-node retrieval is uncapped. It does not describe pagination, size limits, or the shape of the aggregate result.

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 boilerplate, and the default behavior (full structure) is front-loaded before the optional override. The 'DNA double helix' phrasing is evocative rather than informative and slightly dilutes the opening, keeping it from a 5.

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

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

For a single-parameter read-only tool with no output schema, the description covers the call surface adequately, but it leaves the return shape ambiguous — an agent cannot tell what fields a node's 'covenant, stakeholder and implementation rules' actually contain, and there is no output schema to fall back on.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely enriches the terse schema text: it explains that `node` returns that node's covenant, stakeholder and implementation rules, which the schema only calls 'one node's detail'. It also implicitly contrasts with the whole-architecture mode.

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 concrete resource — the Mzizi architecture ('DNA double helix' of nodes, rungs and strands) with live counts — and distinguishes the two modes (whole structure vs. a single node's detail). The metaphor is unusual but the returned artifact is identifiable, and the `node` branch is spelled out. It stops short of cleanly defining what 'nodes/rungs/strands' are, so it is not a textbook 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?

It implicitly gives a routing rule: omit `node` for the full architecture, pass `node` for one node's covenant/stakeholder/implementation rules. That is a real when-to-use signal for the parameter. However, it says nothing about when to prefer this over sibling tools like mzizi_get_doctrine or mzizi_get_component, and gives no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint and a closed-world scope, so safety is covered. Beyond that, the description discloses genuinely useful behavior: the Rust-first ordering, that `rust` is null and `lead` becomes "react" when no Rust exists, that former nyuchi-* names resolve to mzizi-* successors, and that React is maintained but deprioritised. It omits only edge cases such as what happens when the component name is unknown.

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?

Front-loaded with the core action and the Rust-first rationale, and every clause carries information about the return shape rather than filler. It is dense and slightly repetitive in restating the rust/react fields, but no sentence is wasted.

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

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

With no output schema available, the description does the heavy lifting by describing the return structure field-by-field (rust/react, lead, files[], CONTRACT clause, npx line). It is nearly self-sufficient for a two-parameter read tool; the only gap is error/not-found behavior, which is minor.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning the schema does not: `include` pulls in docs (use cases, variants, a11y contract) and version history, and explicitly notes that omitting it returns implementations only. It also clarifies that `name` accepts legacy nyuchi-* aliases, which is not in the schema.

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

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

States a specific verb (fetch) and resource (one component) and immediately distinguishes itself from the sibling list tool by scoping to a single component fetched 'in full'. It goes further by naming the exact shape of what comes back (rust crate, cargo add line, CONTRACT block, .rs source, then the react build), so an agent knows precisely what this returns versus mzizi_list_components.

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

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

The description explains the conditional behavior (Rust-first when a Roots implementation exists, React deprioritised otherwise) and when to use `include`, which is useful implied usage guidance. However, it never explicitly names an alternative tool or states a when-not condition, leaving the agent to infer that mzizi_list_components is the browsing counterpart.

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, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds essentially no behavioral context beyond the schema enum: it does not say what form the doctrine comes back in, whether listing vs. fetching differs, or how much content to expect.

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 short sentence with the framing ('How to build here') front-loaded and the content categories enumerated after. Nothing is redundant or padded.

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, so the description could usefully describe the return shape or volume, and it does not. Parameters are well covered via schema and annotations cover safety, but an agent still cannot tell what a doctrine response looks like.

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

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

Schema description coverage is 100%, so both parameters (topic and optional name) are already fully documented in the schema, giving a baseline of 3. The description adds no syntax or format detail beyond the schema.

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

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

The description names a specific verb-resource pairing (get doctrine) and enumerates the content categories it returns: Ubuntu pillars/principles, mzizi conventions, and AI instruction sets, which map cleanly to the topic enum. It does not, however, explicitly distinguish itself from close siblings like mzizi_get_architecture or mzizi_get_skills, so an agent must infer the boundary.

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?

'How to build here' implies the usage context (fetch project doctrine when you need build guidance), but there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling getters. Guidance 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-derivable context: content is served from skill files bundled at build time and matches mzizi-dev/agent-tools at the deployed commit, telling the agent the data is static, pinned and not fetched live.

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, front-loaded with the action and mode, with the provenance note second. No filler; every sentence carries information an 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?

With one optional parameter, no output schema and annotations covering safety, the description supplies what an agent needs: what it returns (a list or one full skill) and that the content is build-time pinned. A brief note on return shape or size would make it fully self-sufficient, but nothing essential is missing.

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

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

Schema description coverage is 100% and the single parameter already documents 'Skill name. Omit to list all.' The description's 'or fetch one in full' adds a little framing but essentially restates the schema, so the baseline of 3 for high coverage is appropriate.

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

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

States a specific verb and resource ('List the published Mzizi agent skills, or fetch one in full'), and the dual list/fetch mode is explicit. It is readily distinguishable from sibling get_* tools like mzizi_get_doctrine or mzizi_get_architecture by resource, and the name parameter's effect is stated up front.

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?

'Skills are what an agent loads first' gives a clear contextual cue for when this tool is the right one to reach for, and the description conveys both operating modes (list vs. fetch). It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it does not reach a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is fully covered. The description adds content-scope context but no extra behavioral detail such as response size, caching, or stability of the token set; with annotations doing the heavy lifting, a 3 is appropriate.

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 compact sentences with no filler; the content inventory is front-loaded and the actionable tip is placed second. Efficient, though the first sentence is a fairly dense list that borders on catalogue-style rather than directive.

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 optional-parameter read tool with no output schema and annotations covering safety, the description gives an adequate picture of the content domain. It does not describe the shape of the returned token data, but with no output schema and a simple interface the omission is minor.

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

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

Schema description coverage is 100% and the `family` parameter already documents every accepted value, including the 'colors' shortcut and aliases. The description's 'Ask for `colors`' tip largely restates the schema, so it adds little beyond baseline 3.

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

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

The description clearly identifies the resource (the Mzizi brand system design tokens) and enumerates its content categories — colour families, semantic colours, typography, spacing, radii, ecosystem brands. It lacks an explicit verb (the title carries 'Get') and does not distinguish itself from siblings like mzizi_get_architecture or mzizi_get_doctrine, so it is clear but not sibling-differentiating.

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 offers one useful routing hint ('Ask for `colors` to get every colour family in one call'), which guides what value to request. However there is no guidance on when to choose this tool over the many sibling docs/architecture tools, and no exclusions — usage is only implied.

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 cover the safety profile (readOnly, idempotent, closed-world), but the description adds real behavioral context: pagination ceiling (up to 400 rows per call) and the presence of total/hasMore in the response, plus exactly which fields each lean row carries. It does not mention auth requirements or rate limits, hence not a 5.

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, front-loaded with the scope and filtering, then the return shape and routing. The em-dash-heavy second sentence packs a lot in but stays readable; nothing is wasted, though it is dense.

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

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

With no output schema, the description carries the burden of describing returns and does so (lean row fields, total and hasMore), and it covers filtering, paging, and alternatives. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so every parameter including node, rust, type, owner, collection, limit and offset is already documented in the schema. The description restates the filter set and clarifies that rustCrate marks the lead Rust implementation, but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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 ('List components' / registry index) and enumerates the filterable dimensions, which lets an agent distinguish it from mzizi_get_component and mzizi_search without opening any schema.

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

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

Explicitly routes to alternatives: 'use get_component for one component in full, or search when you only have words.' Both the alternative and the condition that selects it are named.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), so the description's value lies in disclosing what comes back — tool inventory, auth requirements, replacement mappings, and data provenance. That return-content framing is genuinely useful given there is no output schema, though it says nothing about cost, size, or freshness of that metadata.

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 with a colon-delimited list of exactly what is exposed — zero filler, no restatement of the title, and every clause carries distinct 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 no input parameters and no output schema, the description carries the burden of telling the agent what it receives, and it does so with four concrete content categories. It is complete for a simple discovery tool, with only minor gaps around when in a workflow it should be called.

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 the baseline is 4; there is nothing for the description to disambiguate. The empty schema matches the parameterless contract described implicitly by the tool.

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

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

States a clear verb+resource (describe this MCP server) and enumerates the specific payload: tools, free vs sign-in status, what each replaces, and data provenance. It does not explicitly distinguish itself from siblings like mzizi_get_architecture or mzizi_get_doctrine, so an agent must infer that this is the broad, meta-level overview rather than a topic-specific lookup.

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 rather than stated: the enumeration of server-wide metadata suggests this is a discovery/first-call tool, but there is no explicit when-to-use, when-not, or named alternative among the many sibling tools. An agent can infer intent, but nothing routes it definitively.

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

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

With annotations only covering the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description carries real weight: it explains the Durable Object desk, fundi reproduction, GitHub filing, issue tracking, history inclusion, and the sign-in requirement. That is rich behavioral context well beyond the structured fields.

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?

Purpose and behavior are front-loaded and every clause carries information, but the run-on construction and repeated references to fundi make it denser than needed. Still efficient for the amount of workflow it conveys.

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 8 parameters, no required fields, and no output schema, the description does a good job covering the lifecycle, statuses, and auth requirement. It stops short of describing the shape of a listed/filed report, but an agent has enough to invoke it correctly.

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 75%, and the description meaningfully supplements the action enum by describing the outcome of 'get' (filed, picked up, closed) and the failure mode 'retry' addresses. It also reinforces the skill parameter's non-inference rule, though it adds little for kind, severity, or component beyond the schema.

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

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

Opens with a specific verb+resource: 'Report a problem with a component or the registry,' and explains the full downstream flow (desk → fundi reproduction → GitHub issue → tracking). It does not, however, differentiate itself from the sibling docs_submit_feedback, which overlaps conceptually given that 'feedback' is a valid kind here.

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

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

Gives explicit action-level routing: "Use 'list' to see your earlier reports and 'retry' to re-attempt one that drafted but could not be logged," and explains what 'get' returns. The gap is that it never says when to choose this tool over docs_submit_feedback or mzizi_fundi, despite an apparent overlap.

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 readOnly, idempotent and closed-world, so the safety profile is covered. The description adds genuinely non-redundant behavior: hit ranking, the rustCrate marker indicating a Mzizi Roots (Rust) implementation, and tie-break ordering by score. It stops short of describing result format or result-count behavior, which keeps it out of the top band.

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

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

Three sentences, each doing distinct work: what is searched, when to use it, how results rank. Scope and entry condition are front-loaded, and there is no filler.

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

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

With no output schema, the description helpfully explains result ranking and the rustCrate marker, and it routes to the docs_* tools. It does not mention result volume or whether paging is needed, a minor gap for a search tool with no limit 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?

There is a single parameter, fully described in the schema (coverage 100%), and the description confirms it is free-text word matching against the registry. That is adequate for a one-argument search; no additional syntax or filter semantics exist to explain.

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 (search) plus the resource and its scope: components, conventions, AI instruction sets and releases. It also explicitly differentiates from the docs_* family, so an agent can place it among siblings without opening the schema.

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?

"Start here when you do not know the exact name of what you want" gives an explicit entry condition, and the closing sentence names the alternative path (docs_* tools for documentation pages). When-to-use and when-to-go-elsewhere are both covered.

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