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 fully established. The description adds value by disclosing the pagination behavior via metadata.next_offset and the notion that long documents require multiple calls; this is useful context beyond the annotations, but no error behavior, auth requirements, or termination conditions are 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?

Two short sentences with the action front-loaded and the pagination guidance placed second. There is no filler or restating of schema details; each sentence earns its place, though the second sentence could be slightly more explicit about parameter semantics.

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

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

The tool is a simple read with rich annotations and only three parameters, and the description covers the key pagination loop needed for long documents. Still, without an output schema, the response shape beyond metadata.next_offset is left to inference, and id semantics remain unexplained, so an agent may still have questions before calling confidently.

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

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

Schema description coverage is 0% and parameter titles ('Id', 'Length', 'Offset') carry no explanatory weight. The description hints at offset/length usage through the next_offset instruction, but it never clarifies what id refers to (search result handle vs document ID) or what units length uses, so the agent must infer critical parameter meaning.

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 'Fetch a search result by ID' names a specific verb and resource, making the core action clear. The need to distinguish from siblings is moderate: among siblings like search and read_file, the search-result framing positions it as the complement to search, but it does not explicitly name any sibling to avoid confusion.

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 pagination instruction ('Follow metadata.next_offset to read a long document completely') conveys clear context for when to use repeated fetches, implying this tool is for retrieving search results incrementally. However, there is no explicit statement of when not to use it or which alternative to prefer (e.g., read_file vs fetch), leaving some routing 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 establish that the tool is read-only, idempotent, and non-destructive. The description adds that the file is 'locally installed', which is useful context, but it does not disclose behavior for unsupported skills or missing files. This is acceptable for a simple read operation but adds only modest value 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.

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

The description is a single, front-loaded sentence with no filler. Every word contributes to identifying what the tool does and what it targets. The only minor issue is the ambiguous word 'either', but structurally it is very concise.

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

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

For a simple read-only tool with annotations covering safety and an output schema present, the description is mostly adequate. However, it fails to enumerate the valid skill values or provide any usage context relative to sibling tools, which leaves a real gap for an agent trying 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?

The schema has one required string parameter with 0% schema description coverage and no enum. The description indicates that 'skill' selects one of the supported management skills, but it never names those skills or explains valid values. This adds minimal meaning beyond the parameter name and leaves the agent guessing about acceptable input.

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

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

The description clearly states the action ('Read') and the resource ('the locally installed SKILL.md'), and it scopes the tool to 'supported management skill'. It is not a tautology and gives enough specificity to distinguish it from generic file-reading or search tools, though it does not name the specific supported skills.

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

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

No guidance is given about when to use this tool instead of siblings like read_file, search, or fetch. There is no mention of prerequisites, fallback tools, or exclusions. The description implies its purpose but does not help an agent choose among alternatives.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds a useful scoping constraint (only registry and indexed Memory/Attention paths; Discussion is excluded), but it does not disclose details like pagination behavior, access requirements, or what happens when a path is invalid. 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.

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

Two short sentences: the first states the resource scope, and the second gives an explicit routing alternative. Every word earns its place, and the key scoping information is front-loaded.

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 list tool with strong annotations, the purpose and main sibling distinction are clear. However, the description leaves several gaps: it does not mention the required project_id, the effect of pagination parameters, or what the returned list contains, and the phrase 'indexed Memory/Attention paths' is vague without defining what 'indexed' means.

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 essentially 0% - the description mentions no parameters by name. The word 'paths' weakly maps to the 'path' property, and the browsing verb implies limit/offset semantics, but nothing clarifies project_id or the meaning of the default values. Since the schema properties have only bare titles and no descriptions, the description should have compensated, and it 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 uses 'Browse' as the verb and names the resource ('registry and indexed Memory/Attention paths'), giving a specific scope. It also distinguishes itself from the sibling 'list_discussions' by directing Discussion-related browsing to that tool. It loses the fifth point because 'browse' is somewhat generic and the description does not specify what kind of files or entries are included.

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

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

The description explicitly routes one key use case ('Use list_discussions for Discussion') to an alternative, which is clear contextual guidance. However, it provides no guidance for other potential alternatives (e.g., search tools or unindexed paths) and does not state when this tool should NOT be used beyond the Discussion case.

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 and idempotent and non-destructive, so the description doesn't need to cover safety. It adds slight context by naming returned fields and pagination, but nothing about data freshness, auth, or side effects. This is acceptable but not rich behavioral disclosure.

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

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

The description is one concise sentence with no filler. It front-loads the primary action and valuable return content, then adds the only parameter guidance worth highlighting. Every word earns its place.

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

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

For a simple list operation with annotations and an output schema, the description is mostly adequate. However, it omits any guidance on the query parameter and does not distinguish from project_overview or refresh_projects, leaving some context for an agent to infer.

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

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

Schema description coverage is 0%, so the description must explain the three parameters. It only explains offset ('Use offset for pagination'), leaving limit and query semantics unexplained. This does not sufficiently compensate for the absent schema descriptions.

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

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

The description clearly states the tool lists discovered projects and includes specific return content (stable IDs, roots, skill versions). It does not explicitly differentiate from siblings like project_overview or list_files, but the verb and resource are specific enough that an agent can infer the primary purpose.

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

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

The description provides clear usage context: list projects and paginate with offset. It does notname alternatives or say when not to use, but the listing intent is clear. This meets 'clear context, no exclusions' rather than the higher bar requiring explicit alternative 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 already establish read-only, idempotent, non-destructive behavior. The description adds useful context beyond annotations by explaining discussion_mode vs discussion_access and warning that mcp_tools may differ from a cached client list. 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.

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

Three sentences and reasonably compact. Each sentence adds some descriptive value, though the opening sentence is grammatically awkward and terms like 'registry' and 'indices' are left undefined. Still appropriately sized.

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 required parameter and no parameter guidance in either schema or description, an agent cannot confidently determine what to pass. Output semantics are partially clarified, but usage context and project_id mapping are 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?

The schema has 0% description coverage for project_id, and the description never mentions project_id or explains how it maps to 'this connection.' The name alone is insufficient, especially since the description emphasizes 'connection' rather than project.

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

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

The description states a specific verb ('Read') and resource ('the registry') and indicates the tool reports Discussion permissions for the connection. However, it doesn't distinguish itself from sibling read/list tools, and 'locate indices' is vague relative to the 'project_overview' name.

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

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

There is no guidance on when to use this tool versus list_projects, read_file, or other siblings. The note about mcp_tools differing from a client's cached list is a caveat, not usage direction.

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?

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses chunking semantics, byte-based addressing, maximum chunk size, base64 preservation of exact bytes, consistency checks across chunks, and access boundaries such as canonical bodies and Discussion being unavailable. None of this contradicts 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.

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

Four short sentences front-load the core purpose first and then supply only high-value constraints and usage details. There are no redundant phrases or explanations that duplicate the schema or annotations.

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 stateful chunked-read tool, the description covers the full invocation loop: read, follow next_offset, validate consistency, restart, size and encoding limits, and permission/resource exclusions. An output schema is present, so return-value shape does not need to be described in prose.

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

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

With schema description coverage at 0%, the description carries the burden. It adds critical parameter meaning: offset and length are byte-based, length has a 262144-byte cap, and base64 encoding preserves bytes. It does not explicitly define path or project_id, but those are reasonably inferable from the tool name and schema titles.

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

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

The description opens with a specific verb-resource pair: 'Read an allowlisted governance document in chunks.' It goes on to precisely bound the resource, name the alternative read_discussion, and enumerate what is 'never available', so an agent can distinguish this from sibling tools like fetch or list_files.

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 explicit protocol guidance: offsets and lengths are bytes, one should follow next_offset to EOF, compare size/modified_ns and restart on change, and respect the 262144-byte maximum chunk. It also states the exclusion for Discussion and points to read_discussion as the proper alternative, so there is no ambiguity about when to invoke this tool.

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

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

The annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description goes beyond them by adding specific safety context: 'No project files are modified.' It also discloses the resume-incomplete-scan behavior, which is useful operational context not available from annotations alone.

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

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

The description is two short sentences with no filler. The primary action is front-loaded, and the second sentence adds relevant safety information without 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 zero-parameter tool with rich annotations and an output schema, the description covers the core behavior, the resume case, and safety guarantees. Nothing essential is missing 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.

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

The tool has zero parameters and an empty input schema, so the baseline is 4. The description adds sufficient semantic context about what the tool does, and there are no parameter details that could be missing.

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

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

The description states a specific action ('Rescan local roots for projects') with a clear resource and scope, and adds a distinct second behavior ('resume an incomplete scan'). This differentiates it from sibling tools like list_projects, which merely lists projects without scanning.

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

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

The description implies when to use the tool: when a rescan or resumed scan is needed. However, it does not explicitly contrast with alternatives such as list_projects or state when not to use it, leaving usage guidance 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 signal read-only, idempotent, non-destructive behavior, so the description adds value by disclosing that only allowlisted documents are searchable, content files must be UTF-8 and under 256 KiB, and results may be truncated. This is meaningful operational 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.

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

The description is compact and well-structured: the first sentence establishes purpose and output, and the second states technical constraints with an actionable mitigation. Every sentence earns its place without 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?

Given the output schema covers return shape, the description covers the rest of the decision space: allowed document scope, cross-project search, the citation-id handoff to fetch, the 256 KiB limit, and truncation handling. An agent has enough context 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.

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 four parameters. It gives useful semantic context for project_id and glob via the truncation guidance, and query is implied, but the limit parameter is not described at all. This is partial but not complete compensation.

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 identifies a specific action (search), a distinct resource (allowlisted governance documents), and a clear cross-project scope. Mentioning that it returns citation IDs for fetch further distinguishes it from sibling tools like read_file or fetch.

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

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

The description provides clear usage context: search across governance documents and use fetch with the returned citation IDs. It also gives practical guidance to narrow project_id/glob if truncation occurs, though it does not explicitly enumerate when not to use this tool versus each sibling.

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