Koskamo

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive, so the safety profile is covered structurally. The description adds one genuinely non-obvious trait — that live-check and source-verification are independent states — which affects how results should be interpreted. It says nothing about empty result sets, result-set breadth, or how pagination behaves in practice.

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 resource and then the filter surface; minimal waste. The closing sentence on live-check/source-verification is compressed to the point of being slightly opaque out of context, but it earns its place as output interpretation.

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 10 optional parameters, an output schema in place, and rich annotations, the description does not need to explain return values. Still, for a faceted search tool it leaves filter-combination semantics and pagination expectations unstated, which is a meaningful gap at this parameter count.

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 70% with seven enums, so the schema already carries most semantics, including the important note that behavior matches only explicitly advertised annotations. The description reinforces the filter axes (publisher, transport, capabilities, sign-in) but adds no matching rules for query, no guidance on combining filters, and no explanation of limit/offset interplay beyond what the schema states.

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 and a two-part resource ("Find remote MCP servers and local MCP packages"), which tells an agent exactly what universe is being searched. It is clearly a discovery/list tool rather than the get-by-id sibling, though it never names koskamo_get_mcp_server or koskamo_register_mcp_server to make the boundary 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?

The list of filter dimensions implies a faceted search use case, but there is no statement of when to reach for this versus koskamo_get_mcp_server (lookup by known id) or how it relates to registration. Usage is inferable from context, not 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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: deleted documents are included, and only approved revisions contribute versions. It says nothing about pagination semantics or result size, though the schema partially covers paging.

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 no filler; the scope and content of the result lead the sentence rather than trailing. It is dense but 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?

Annotations cover the safety and idempotency profile, the output schema covers return shape, and all three parameters are fully described in-schema, so the description does not need to repeat those. What remains thin is the relationship to sibling tools, which is the description's remaining job.

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%, with limit, offset, and dataset all documented in-schema, so the baseline is 3. The description adds only that the dataset must be 'public', which is a mild constraint beyond the schema but not a clarification of any specific parameter's semantics.

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 ('Get the document version timeline') and scopes it to a public dataset, spelling out exactly what is returned (every document including deleted ones with approved-revision history). It never names the adjacent siblings koskamo_list_revisions or koskamo_retrieve, so an agent must infer the boundary from the wording alone.

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 only implied: 'for a public dataset' and 'version history produced by approved revisions' hint at when this applies but give no explicit when-to-use, when-not, or named alternative. No guidance on how this differs from koskamo_list_revisions, which is the most likely point of confusion.

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, openWorld and non-destructive, so safety is covered. The description adds real value beyond that: it discloses the returned payload scope (live-observed vs source-attributed schemas, resources, prompts, package definitions, provenance, sanitized maintenance events), which tells the agent how rich and how trustworthy the record will be.

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 the verb and scope first, then the payload enumeration. It is dense but every clause describes actual returned content rather than restating the name; 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?

Given an output schema exists and annotations cover the safety profile, the description only needs to establish what record is fetched and how it differs from the finder. It does that adequately; the only shortfall is the absence of an explicit alternative/pivot statement.

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 with 100% schema description coverage ('Directory listing id'), so the schema carries the semantics. The description's 'published MCP listing' mildly narrows what the id can refer to, but adds no format or lookup-failure detail. 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+resource: 'Get one published MCP listing.' The singular, id-keyed retrieval is clearly distinguishable from the sibling koskamo_find_mcp_server search tool, though that sibling is not named. The enumerated payload contents reinforce what kind of record this returns.

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 only implied: 'one published ... listing' plus a required id signals direct lookup by identifier. There is no explicit statement of when to use this versus koskamo_find_mcp_server (discovery) or koskamo_get_history (version history), so an 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by indicating the datasets are public and that pagination continuation metadata is part of the operation.

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 redundant or filler content. Every phrase contributes to the stated purpose, scope, or pagination behavior.

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 has rich annotations, a complete input schema, and an output schema, so the description need not explain return values or safety. It adequately states the public scope and pagination nature, though it could mention ordering or relationship to sibling retrieval tools for fuller context.

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%, with both parameters fully documented in the input schema. The description does not add detailed semantics beyond the schema, but its mention of 'page' and 'continuation metadata' aligns with limit and offset, so the baseline score of 3 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?

The description uses a specific verb and resource: 'List a page of public Koskamo datasets.' It clearly describes scope ('public') and pagination ('page', 'continuation metadata'). It does not explicitly distinguish this tool from siblings such as koskamo_retrieve, 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?

The description implies that this tool is used to browse paginated public datasets, but it does not state when to use it instead of alternatives like koskamo_retrieve or koskamo_get_history. No explicit exclusions or prerequisites are provided, 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only that results are limited to pending revisions for a dataset; it says nothing about pagination behavior, authorization, or rate limits beyond what the schema and 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?

The description is a single front-loaded sentence with no wasted wording. It is appropriately concise, though its brevity contributes to gaps captured under usage and completeness.

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 list operation with an output schema and rich annotations, the description is minimally sufficient to identify the action. However, it omits sibling differentiation, the meaning of 'pending revisions' in this system, and any note about the dataset parameter's expected value.

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 67%; limit and offset are documented in the schema, while the required 'dataset' parameter has no schema description. The description compensates minimally by saying the revisions are 'for a dataset,' but it does not explain the dataset identifier format or further constrain the parameter.

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 and resource: 'List pending revisions for a dataset.' This is clearer than a tautology and the word 'pending' narrows the scope, but it does not distinguish the tool from siblings such as koskamo_get_history or koskamo_retrieve.

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 guidance on when to use this tool versus alternatives. The phrase 'pending revisions' implies a use case, but no alternatives, exclusions, or prerequisites are mentioned.

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 destructive=true, idempotent=false, and openWorld=true; the description adds genuinely new behavioral context — a live check gates publication, the owner key is returned exactly once, the email confirm link is single-use, and the contact email receives one confirmation message and grants no ownership. It does not disclose what a re-call with an existing id does (overwrite/edit vs. error), which matters given destructiveHint=true.

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 two-call flow, then the proof-method alternatives, then the optional contact email. Sentences are long and dense but nearly all carry decision-relevant information; some content duplicates schema descriptions (proofEmail rules, confirm-link behavior).

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 16-parameter, two-call, destructive publishing tool with an output schema and full schema coverage, the description supplies what structured fields cannot: the ordering of the two calls, the gate condition for publication, the one-time owner key, and the email fallback with its human-in-the-loop step. Return values need not be restated because an output schema exists, so nothing an agent needs in order to call it correctly 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 schema already documents token provenance, proofEmail domain restrictions, and method semantics in comparable detail. The description reinforces the first-call/verify-call split and the token's role but adds little that the schema does not already state. Baseline 3 is appropriate when 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 and resource — list/publish a remote MCP server in the Koskamo MCP directory — and immediately frames the two-call protocol (validate-then-verify). It is clearly distinguishable from read-oriented siblings like koskamo_find_mcp_server and koskamo_retrieve, though no sibling is named explicitly. The word 'List' for a publishing action is slightly at odds with the tool name 'register', but the phrase 'the listing is published' resolves it.

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 procedural guidance: a call without token validates fields, a call with id+token verifies proof and runs a live check, and 'Nothing is listed without both.' It also lays out the proof-method alternatives (HTTP well-known, DNS TXT, or email) and when email applies. It stops short of routing the agent to or away from specific sibling 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?

The description adds real context beyond the annotations: no API key is required, the submission goes into a reviewer queue, and published content is not modified. That last point usefully reframes the destructiveHint=true annotation, clarifying that the write is an additive report rather than an edit to live content. It does not say whether submissions can be retracted or duplicated (relevant given idempotentHint=false), which keeps it off 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 short sentences, front-loaded with the action and followed by the two facts an agent most needs (no auth, non-destructive to published content). No filler or restatement of the title.

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 rich annotations and an output schema present, the description only needs to supply the post-call behavior, which it does. The remaining shortfall is guidance on choosing between the mutually exclusive passage/query fields and on what a caller should expect from the returned report handle.

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 83% and the schema itself documents note, query, dataset, passage and document_id well, so the baseline of 3 applies. The description adds no parameter-level detail beyond restating the category of dispute, leaving a mild gap around how passage and query interact when only one is supplied.

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 and resource ('Submit a disputed passage for review') and qualifies it with the exact failure modes that motivate the call (wrong, outdated, missing source). Nothing in the sibling list (find/list/retrieve/register/history) could be confused with this write-a-report action.

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 clearly states the triggering condition — use this when a passage may be wrong, outdated, or missing a source — which maps directly onto the reason enum. It does not name an alternative (e.g. retrieve or list_revisions) for the case where the agent simply needs to re-read content, so it stops short of explicit when-not 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?

The description adds critical behavioral information that goes beyond the structured hints, specifically stating that 'Similarity scores rank matches and do not measure factual confidence.' This manages user expectations regarding the accuracy of the retrieved data, which is vital for an LLM agent.

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 two sentences are extremely efficient. The first defines the scope and target resource, while the second immediately provides a critical caveat about the output quality, avoiding unnecessary fluff.

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 description covers the resource (passages), the source (Koskamo datasets), the action (search/retrieve), and the inherent limitation (similarity vs. factual confidence). Given the strong annotations and defined schema, this context is functionally complete for a retrieval 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?

The schema coverage is moderate (67%). The description does not elaborate on the semantics of the parameters (e.g., why 'query' should be a question vs. a keyword, or how 'top_k' affects performance). It adds functional context rather than clarifying schema data.

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 performs a search ('Search Koskamo datasets') to retrieve specific entities ('candidate passages') with unique attributes ('source citations and document versions'). This is distinct from the siblings which deal with listing, registering, or reporting facts.

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 tool provides clear usage context by specifying that it searches within 'Koskamo datasets' and that it uses similarity scoring for ranking. While it doesn't explicitly state 'do not use this if you want to list datasets,' the function's purpose highly distinguishes it from sibling tools like koskamo_list_datasets.

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