Koskamo

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds valuable context: it requires the dataset owner's API key or KNOWLEDGE_ADMIN_KEY, and it discloses that approved text is chunked and becomes retrievable. This goes beyond the annotations and helps the agent understand side effects and authorization requirements.

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 sentences, front-loads the core action, and every sentence adds value: the first states the action, the second covers authorization and consequences. No wasted words.

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 action, authorization, and side effects, and the output schema exists to explain return values. It does not explicitly mention that rejection has no chunking side effect, but that is implied by 'Approved text is chunked'. For a decision tool with an output schema and clear annotations, this is nearly complete.

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%, with revision_id and decision already described in the schema. The description adds context for revision_id by referencing the sibling tools that return it, and it clarifies the decision values implicitly through 'Approve or reject'. However, it does not add much detail about the 'note' parameter, which is the only parameter not described in the schema. The description is adequate but not exceptional.

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 ('Approve or reject a pending revision') with a specific verb and resource, and distinguishes it from siblings like koskamo_propose_revision and koskamo_list_revisions. It also adds the consequence of approval ('Approved text is chunked and becomes retrievable'), which clarifies the tool's role in the workflow.

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 this tool: after a revision has been proposed and is pending, and it names the sibling tools that produce the revision_id. It does not explicitly state when not to use it or name alternatives for other actions, but the context is clear enough for an agent to select it appropriately.

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 this is a safe read-only, idempotent operation. The description adds meaningful behavioral detail beyond the annotations by stating that deleted documents are included and that only approved revisions contribute to the history, which is valuable context for interpreting results.

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 entire description is one well-structured sentence with no filler. The core action and resource come first, followed by the important inclusions (deleted documents, approved revisions), making it easy to scan and understand quickly.

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?

This is a simple one-parameter read-only tool, and the output schema already exists. The description covers the key behavioral scope, the parameter is fully documented by the schema, and annotations cover the safety profile. No critical information 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 is already documented as 'Dataset id or slug'. The description does not add new semantic detail about the parameter itself, 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 ('Get') and resource ('document version timeline') and clarifies the scope: every document including deleted ones, restricted to approved revisions. This makes the tool's purpose immediately distinguishable from sibling tools like koskamo_list_revisions 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?

The description implies the tool is for viewing version/history information for a public dataset, but it does not explicitly state when to choose this over koskamo_list_revisions or koskamo_retrieve. The intended use is clear enough to infer, but no exclusions or alternatives 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds 'public' and 'may retrieve from,' which is useful scoping context beyond the schema. However, it does not disclose pagination or response format, but that is partially handled by the output schema.

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

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

The description is a single sentence that front-loads the verb and object, contains no filler words, and communicates scope and purpose efficiently. 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 zero-parameter, read-only listing tool with an output schema and rich annotations, the description is adequate. It explains what the tool does and its scope. It could mention that the output is a list of dataset identifiers, but the output schema already provides that detail.

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 are zero parameters, so schema description coverage is trivially 100%. The description does not need to explain any parameters. For a tool with no parameters, the baseline is 4, and nothing is 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 verb and resource: 'List public Koskamo datasets' and clarifies the purpose with 'an agent may retrieve from.' This distinguishes it from siblings like koskamo_list_revisions (which lists revisions) and koskamo_retrieve (which retrieves a specific dataset).

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 the usage context: an agent would list available datasets before retrieving one. It does not explicitly name alternatives or say when not to use this tool, but the phrase 'an agent may retrieve from' provides clear contextual guidance. Lacks explicit exclusions, hence not 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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. However, the description adds no extra behavioral context such as what 'pending' means, ordering, pagination, or any side effects. It does not contradict annotations, but it also does not enrich them, leaving the meaning of 'pending' undefined.

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, compact sentence with no redundancy. It is front-loaded with the core action and resource. While minimal, it is appropriately concise for a tool of this simplicity.

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 are documented elsewhere. However, the description is too terse to fully guide an agent: it does not explain what constitutes a 'pending' revision, nor does it clarify the dataset parameter. Given the 0% parameter coverage and the existence of overlapping siblings, the description leaves gaps that could lead to incorrect 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?

The schema has one parameter, 'dataset', with no description (0% coverage). The description mentions 'for a dataset' but does not clarify its format, allowed values, or semantics. The description fails to compensate for the complete lack of schema documentation, leaving the agent to guess what a valid dataset string looks like.

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 clear verb ('List') and a specific resource ('pending revisions') scoped to a dataset. It does not explicitly differentiate from sibling tools like get_history or list_datasets, but the resource is specific enough that an agent can infer the intent.

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 provided on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or comparative context with siblings like koskamo_propose_revision or koskamo_decide_revision. The agent must infer usage solely from the name.

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?

It discloses the key behavioral trait that changes are not applied immediately and await owner approval. This complements annotations like destructiveHint=false by clarifying that even delete proposals are pending, not directly destructive.

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 enumerates the operations and the pending-approval workflow with no filler or redundant repetition of schema details.

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 tool with 8 parameters and an output schema, the description supplies the crucial workflow context (pending approval) and enough orientation to choose between actions. It could more directly tie the prose operations to the action enum values, but the schema already handles that.

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 input schema already covers 75% of parameters with descriptions. The tool description adds little beyond mapping actions like 'reverting' and 'deleting' to the schema's action enum, so the baseline 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 specific verbs ('propose', 'reverting', 'deleting') and names three distinct operations. It also distinguishes from siblings by noting the change stays pending until approval, implying a separate decision tool finalizes 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?

The description gives three explicit use cases: proposing a better fact, reverting to an earlier version, and deleting a document. It signals that this tool only creates pending changes, which routes final approval elsewhere, though it does not explicitly name the alternative 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?

Annotations already cover the read-only, non-destructive, idempotent, and open-world profile. The description adds useful behavioral context beyond those annotations by clarifying that the tool searches public datasets and returns cited passages, which tells the agent what kind of evidence it can expect and that no private-data access is assumed.

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 efficient sentence that front-loads the core action and resource, then adds a purposeful rationale. Every clause earns its place, with no redundant or filler wording.

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 simple, has an output schema, and annotations cover its safety profile. The description together with the schema covers what query to provide, the optional dataset filter, and the top_k bounds. It could be more complete by explicitly distinguishing itself from sibling list/propose tools, but nothing essential is missing for 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 67%: query and dataset are described, but top_k is not. The tool description does not add parameter-level meaning beyond the schema, and it does not compensate for the undocumented top_k parameter. It slightly reinforces the dataset scope but otherwise leaves parameter semantics to 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 states a specific verb ('Look up'), a clear resource ('cited passages from public Koskamo datasets'), and an explicit purpose ('answer from facts instead of guessing'). This distinguishes it from sibling tools like list_datasets and propose_revision, which serve different operations.

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 a clear intended context: use this tool when the agent needs cited evidence to ground an answer. It does not explicitly name alternatives or when-not-to-use conditions, but the purpose clause effectively frames when retrieval is appropriate relative to the other revision/list tools.

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