Colink MCP

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

Annotations already establish readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description goes beyond that by disclosing two real behaviors: no version numbering is required, and a single-state project diffs against an empty project. It does not mention result format or size, but the output schema exists for that.

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

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

Three sentences, front-loaded with the core purpose before the parameter conditions. Slightly dense and the phrase "no numbered versions needed" is a bit oblique, 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 an output schema present, return values need not be explained, and the description covers all three parameters plus the edge case of a single initial state. What remains missing is any indication of comparison scope limits or relationship to sibling tools.

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 carry the parameters, and it does: snapshot is an opaque handle that can be omitted for current code, and path narrows the diff to one file. project_id is only implicitly covered, which is the one small gap.

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+resource ("Review the latest code changes against the preceding state"), which reads as a diff-retrieval operation and is distinguishable from read_file/search_code/repo_overview by its comparative scope. It never names a sibling explicitly, so differentiation is inferential rather than stated.

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 conditional usage for parameters ("Omit snapshot for current code", "With only one initial state, compare against an empty project"), which is real guidance, but it never says when to prefer get_diff over repo_overview or search_code. Usage is implied through parameter conditions rather than stated as a routing decision.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely useful piece of context — that context handles are internal identifiers rather than display labels — but says nothing about ordering, scope, or filtering behavior.

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 no filler, and the core purpose is front-loaded. The second sentence is terse to the point of being cryptic, but it is not 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?

An output schema exists, so return values needn't be explained, and there are no parameters to document. Still, for a discovery tool sitting beside repo_overview, the description leaves the project-vs-repo relationship and the expected usage flow unstated.

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

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

Zero parameters, so per the rubric the baseline is 4. The note that 'context handles are internal, not user-facing labels' is about output labeling rather than inputs, so it doesn't shift this dimension.

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: 'Find available code projects.' This is distinguishable from siblings like repo_overview, read_file, search_code, and get_diff, which all operate on code content rather than enumerating projects. However, it never clarifies how a 'project' relates to a 'repo' in this ecosystem.

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

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

No guidance on when to call this versus siblings such as repo_overview, nor any prerequisites or ordering advice. The intent (discover projects before acting on them) 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context: default 200 and max 1000 lines, snapshot consistency semantics, and output-reporting guidance ("report code findings, not handles, hashes..."). That is more than the annotations provide.

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

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

Front-loads the purpose, then adds two compact clauses on snapshot semantics and reporting. Dense but every sentence carries information; minor awkwardness in the mid-clause aside, it is 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?

An output schema exists, so return-value detail is unnecessary, and the description covers the non-obvious snapshot and line-limit behavior. Given the low schema coverage, project_id and path could be clarified, 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 description coverage is 0%, so the description must carry the load. It explains snapshot values well and the default/max line count maps to start_line/end_line behavior, but path and project_id are left entirely undocumented. Partial compensation only.

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+resource ("Read source") and ties it to a goal ("answer code questions"), which distinguishes it from list_projects, search_code, and get_diff. It references repo_overview's handle, but does not otherwise differentiate itself from siblings that also surface code, so it falls short of a 5.

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

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

Provides condition-based guidance for the snapshot parameter (omit for current, 'previous', or reuse a repo_overview handle), which is genuinely useful. However, it never states when to prefer read_file over search_code or get_diff, so usage relative to alternatives remains 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 declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely new behavioral context: retention is limited to current and previous code, handles expire and require a fresh analysis, and the handle must not appear in the answer. That lifecycle detail goes well beyond the annotations.

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

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

Short, front-loaded, and every sentence carries information about the snapshot/handle lifecycle. The phrasing is terse to the point of being cryptic in places ("do not include it in the answer"), but 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?

An output schema exists, so return shape need not be described, and the description covers the tricky part (snapshot selection, handle reuse, expiry). Missing only pagination behavior for limit/offset and any hint of result size, which is minor given the output schema.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does explain the snapshot parameter's three modes and the handle contract thoroughly. But limit, offset, and project_id receive no explanation at all, leaving pagination semantics undocumented.

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+resource ("List code files"), so an agent knows the basic operation. However, it never distinguishes itself from siblings like read_file or search_code, and the name "repo_overview" suggests something broader than a file listing, leaving a small ambiguity about scope.

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 concrete guidance on the snapshot argument (omit for current code, use 'previous', or reuse a handle) and on passing handles to follow-up reads, which implies a workflow. But it never says when to choose this tool over read_file, search_code, or get_diff, so sibling selection is left 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description adds real behavioral detail on matching semantics (literal, case-sensitive) and the snapshot-handle lifecycle, including the caution to keep handles out of the answer. It stops short of describing result ordering or pagination behavior.

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 core behavior and no filler. The trailing 'Keep handles out of the answer' is terse and slightly ambiguous but earns its place as an operational caution.

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?

An output schema exists, so return values need no explanation here. With matching semantics, snapshot modes, and the safety profile covered by annotations, the definition is nearly sufficient; only limit/pagination behavior is unaddressed.

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 carry the load. It does explain query semantics (literal, case-sensitive) and snapshot modes, but says nothing about limit or project_id, leaving two of four parameters undocumented anywhere.

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 ('Locate literal, case-sensitive code text') plus what is returned ('paths and lines'). It does not explicitly contrast itself with read_file or get_diff, but 'search' vs 'read' is a reasonably clear split for an agent.

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 snapshot guidance ('Omit snapshot for current code, use previous, or reuse an opaque handle') is useful mode-selection advice, but it is parameter usage rather than tool-selection guidance. There is no statement of when to prefer this over read_file or get_diff, so 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.