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

With no annotations, the description carries full burden. It describes the 'auto' section walking order but does not disclose whether the operation is idempotent, what happens if the section doesn't exist, or potential side effects. It adds some context but leaves gaps.

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-loaded with the main action, and every sentence adds value without fluff. It is efficiently structured.

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 no output schema and no annotations, the description adequately explains the tool's purpose and key behaviors (auto section walking, usage scenario). It could mention the return value or error cases, but it is fairly complete for a grafting operation.

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 50%. The description adds context about grafting evidence but does not elaborate on findingId or caption beyond what the schema provides. The section parameter's alias system is already well-documented 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?

The description clearly states the tool grafts an already-uploaded attachment into an existing finding's body at a named section, using a specific verb ('graft') and resource ('finding'). It distinguishes from siblings by referencing konsulto_attach_evidence and focusing on post-creation evidence addition.

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 says 'Use this when adding evidence after the finding was created' and gives examples, providing clear context for when to use. However, it does not mention when not to use it or compare to alternatives like konsulto_append_to_section.

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?

No annotations are provided, so the description carries the full burden. It discloses that content is markdown and converted to rich-text, but omits details on idempotency, error handling, or permission 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?

Three concise sentences, no wasted words. The first sentence states the core action, second provides usage context, third clarifies format. Front-loaded and effective.

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 append operation, the description covers input format and conversion behavior. It does not address edge cases like nonexistent sections or content length limits, but is sufficient for typical usage.

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%. The description adds meaning to 'section' by listing canonical names and aliases, and to 'content' by specifying markdown prose. However, 'findingId' lacks description in both schema and description.

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 verb 'Append' and the resource 'named section of a finding', distinguishing it from siblings like konsulto_read_section and konsulto_replace_section.

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 guidance on when to use: 'Use this to add a paragraph or two without touching the rest of the finding.' It implies when not to use (replace full section) but doesn't explicitly list 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?

No annotations provided; description fully bears burden. Discloses that exactly one of three content sources must be set, returns evidenceId, and does not link to findings. Lacks size limits or error behavior, but sufficient for safe use.

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 focused sentences: action+return, sibling usage, constraint. No wasted words, front-loads purpose.

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 no annotations or output schema, description covers purpose, return, sibling links, input constraint, and default filename. Could add size limit or error info, but overall complete for decision-making.

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 covers 83% of parameters with descriptions. Description adds the critical one-of constraint and default filename behavior not in schema. Adds meaning beyond schema without redundancy.

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?

Clearly states it uploads a file or inline content as an attachment, returns evidenceId, and distinguishes from linking tools. Verb 'upload' with specific resource 'attachment in active audit'.

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 tells agent to pass evidenceId to konsulto_add_evidence_to_finding or include in konsulto_compose_finding's evidence array. Also states 'does NOT link to a finding by itself', precluding misuse.

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?

No annotations, so description carries burden. Discloses bulk operation and dryRun preview, but lacks details on reversibility, permissions, or partial failures.

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 purpose, minimal waste. Efficient for agent consumption.

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?

Covers main use case with safety tip. Lacks details on error handling and atomicity, but sufficient for typical usage given sibling 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 has 0% description coverage. Description partially explains parameters (bulk implies findingIds, status change, dryRun mentioned), but doesn't detail enum values or constraints.

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 changes status of many findings at once, with specific examples. It distinguishes from sibling 'konsulto_update_finding' by emphasizing bulk operation.

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 use cases and recommends dryRun first. Missing when not to use but context is clear enough.

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?

No annotations are provided, so the description carries the full burden. It discloses key behaviors: 'The backend builds the Tiptap body from a layout' and explains how evidence is grafted. It also warns against passing Tiptap JSON. Missing details on return value or error conditions, but overall sufficient.

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-loaded with purpose and immediate guidelines. No redundant or extraneous information. Every sentence adds value.

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 complexity (6 params, nested objects, no output schema, no annotations), the description covers essential aspects: creation, field formats, evidence insertion, template usage. It lacks return value info but is otherwise complete enough 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?

The description adds significant value beyond the input schema. It clarifies that fields should be plain prose, stepsToReproduce as array of strings, and that fields is open-ended for template slot names. It also explains the evidence section behavior and the 'auto' walking order. Schema coverage is 50%, but the description compensates fully.

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's purpose: 'Create a brand-new finding from structured fields + optional template + optional evidence.' It uses a specific verb ('Create') and distinct resource ('finding'), differentiating it from sibling tools like konsulto_update_finding or konsulto_add_evidence_to_finding.

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 explicit formatting rules: 'NEVER pass Tiptap JSON as a field. Use plain prose for summary/impact/remediation, an array of plain strings for stepsToReproduce.' It also explains evidence insertion semantics. However, it does not explicitly state when to use this tool over alternatives, though the context implies it.

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?

No annotations are provided, so the description must carry the full burden of disclosing behavioral traits. While it indicates a creation operation, it omits side effects (e.g., duplicate detection, required permissions, whether it modifies audit state) and does not hint at return values or error conditions.

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 with no redundant information. The purpose is front-loaded, and the second sentence adds actionable usage context. 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?

Given the complexity (6 parameters, nested objects, no output schema), the description covers the usage scenario and follow-up but fails to explain what the tool returns (e.g., asset ID) or highlight required fields beyond what the schema provides. It is adequate but has gaps.

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%, so the schema already documents most parameters well. The description adds marginal value by referencing host/URL/IP, which aligns with the identifiers and type parameters, but does not provide additional meaning 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 clearly states the action ('Create a new asset') and the context ('in the active audit'). It also distinguishes from sibling tools by specifying the trigger (scan/evidence reveals untracked host/URL/IP) and suggesting a follow-up tool (konsulto_link_asset).

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 tells when to use the tool ('when a scan or evidence reveals a host/URL/IP that isn't yet tracked') and provides a recommended next step, but does not include explicit what-not-to-use or alternatives beyond the implied difference from other 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?

With no annotations, the description fully carries the burden. It lists all returned fields, indicates it's a read operation, and describes the default/override behavior. No contradictions or omissions.

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 concise sentences, front-loaded with the core purpose. Every sentence is informative with 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?

Given the tool's low complexity (1 param, no output schema), the description is fully complete: it explains purpose, usage timing, returned data, and parameter behavior.

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 baseline is 3. The description reinforces that 'audit' defaults to active audit and can be overridden, but adds no new details beyond what the schema already provides.

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 it is a 'one-shot orientation tool' that returns specific audit context fields like name, status, dates, counts, and team. This distinguishes it from sibling tools that handle findings, assets, sections, etc.

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 says to call at session start after 'whoami' to ground yourself before doing work. Also explains default behavior and override with 'audit' parameter, providing clear when-to-use and how-to-use 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?

No annotations provided, so description carries the burden. It mentions returning markdown body and structured fields, and implies read-only behavior. However, it does not disclose error handling, missing results, or any side effects.

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 concise sentences that front-load the purpose and include key details 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 single-parameter read operation, the description adequately covers the return content (markdown body and structured fields). Missing minor details like error behavior, but overall sufficient given low complexity.

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 has 0% description coverage. The description mentions 'by ID' but does not explain the format, examples, or constraints for the required 'findingId' parameter beyond what the schema provides.

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 'Read a single finding by ID' with a specific verb and resource, and distinguishes from siblings like konsulto_search_findings and konsulto_update_finding.

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 says 'Use when the user asks to review, explain, or summarize a specific finding', providing clear context for when to use. While it doesn't list when not to use, siblings imply alternative tools for different actions.

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 no annotations, the description carries full burden. It discloses match-or-create via case-insensitive substring, and that it patches the finding's assets array. It lacks details on permissions, side effects, or error handling, but covers the core behavior well.

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 three sentences, front-loaded with the core action, then details, then usage example. No redundant or unnecessary 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?

Given no output schema or annotations, the description explains the main behavior and usage scenario. It lacks details on return values, error cases, and any prerequisites, but is adequate for a moderate-complexity 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?

Schema coverage is 67% (2 of 3 parameters have descriptions). The description reinforces the schema but adds limited new information: it clarifies that assetHint is used for match-or-create and assetType only for creation. findingId is not described in either place.

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 'Attach an asset to a finding' and explains the match-or-create logic. It distinguishes itself from sibling tools like konsulto_create_asset by combining matching and creation, and provides a concrete example of when to use 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 includes explicit guidance: 'Use this when the user says...' This tells the agent the specific scenario for using the tool. However, it does not explicitly list alternative tools or state when not to use it.

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?

No annotations are provided, so the description carries the burden. It indicates a read operation ('list') and specifies return fields, but it does not disclose behavior like pagination (despite the limit parameter), potential large result sets when listing tenant-wide, or any permission requirements. The description is adequate but lacks depth on side effects or resource consumption.

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 exceptionally concise: two sentences that immediately convey purpose, scope, return content, and a related tool. No extraneous information. Every word is justified.

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 explains return fields (name, type, identifiers) and mentions matching evidence. The three parameters (audit, q, limit) are covered enough for basic usage. However, it could be more complete by noting that results are paginated via the limit parameter, and that tenant-wide listing may return many assets. Overall, it is fairly complete for a list operation.

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% (audit and q have descriptions). The description adds value by explaining the audit parameter's scope effect ('in the audit or tenant-wide') and stating return fields. However, it does not describe the limit parameter (not in schema description either) and 'q' is already explained in schema. The description partially compensates for the missing schema documentation but leaves a gap for limit.

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 ('list assets'), the resource ('assets'), and the scope ('in the audit or tenant-wide if no audit filter'). It also mentions the returned fields (name, type, identifiers) to help match evidence. This distinguishes it from sibling tools like konsulto_create_asset (create) and konsulto_link_asset (link).

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 a clear use case: 'match evidence to the right asset' and directs to use konsulto_link_asset for attaching. It implies when to use this tool (listing assets) but does not explicitly state when not to use it or list alternative tools. However, the guidance is helpful and context-appropriate.

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?

No annotations provided, so description carries full burden. It states the scope (user's team members) and filtering capability. However, does not disclose pagination, ordering, or whether it returns full audit details or just IDs. Basic but lacks deeper behavioral insights.

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: first states function, second states usage and filter. No unnecessary words, front-loaded with key action.

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 no output schema and simple list tool, description is adequate for its purpose. It explains how to find audit ID, which aligns with sibling tools. Could mention limit parameter or return data format, but not essential.

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 50% (status described, limit not). Description repeats status filter from schema but adds nothing for limit. Baseline 3 reduced because description fails to compensate for missing limit description.

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?

Description clearly states it lists audits where the user is a team member, with a specific purpose: to find the audit ID to work in. This distinguishes it from siblings like konsulto_search_templates or konsulto_list_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?

Explicitly states usage context: find audit ID for subsequent work. Implies it is a prerequisite for tools requiring an audit ID. No explicit when-not-to-use or alternatives, but context is clear.

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 discloses the default behavior ('defaults to the active audit'), which is the key behavioral trait beyond a simple list operation. However, with no annotations provided, it lacks details on idempotency, side effects (none expected), or any rate limits, though the tool is simple enough that this is adequate.

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-loaded with the action and immediately followed by use-case and default behavior. Every word serves a purpose with no redundancy or 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?

Given the tool's simplicity (one optional parameter, no output schema, no annotations), the description covers the essential purpose, usage context, and default behavior. It could mention that scope elements are typically predefined, but the current level is sufficient for confident 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 description adds no additional meaning for the single parameter beyond what is already in the input schema, which fully describes the audit ID and default. Since schema coverage is 100%, 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 clearly states the verb ('List') and resource ('scope elements for an audit') with specific context ('what's authorized to be tested'). It distinguishes this from sibling list tools like konsulto_list_assets or konsulto_list_my_audits, making the tool's purpose unambiguous.

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 provides explicit guidance on when to use the tool ('confirm targets are in-scope before recording findings'), but does not mention when not to use it or name alternative tools for similar tasks, such as checking findings via search_findings.

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?

No annotations are provided, so the description carries the full burden. It mentions returning markdown, accepting aliases, and server-side mapping. It could explicitly state it's read-only, but the verb 'Read' implies no side effects.

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 key action and resource. Every sentence adds value: purpose, examples, differentiation, parameter hint. 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?

Given the tool's simplicity (2 params, no nested objects, no output schema), the description is complete. It explains return format (markdown), alias behavior, and when to use. No gaps remain.

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 description adds meaning to the 'section' parameter by listing aliases (summary, recommendations, etc.) beyond the schema's canonical list. For 'findingId', it adds no extra info, but schema coverage is 50% and the description compensates well for section.

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 reads 'just one section of a finding's body as markdown' and gives concrete examples ('explain the POC', 'summarize the impact'). It distinguishes itself from the sibling konsulto_get_finding by highlighting cost savings.

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 tells when to use: 'when the user only cares about one section', and contrasts with the more expensive alternative konsulto_get_finding. Also implies when not to use (when multiple sections needed).

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 discloses that previous content is preserved on the audit trail (recoverable) and that content is markdown, which are important behavioral traits. No annotations are provided, so the description carries the full burden; it covers the key behaviors well but could mention what happens if the section does not exist.

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 very concise with two front-loaded sentences that efficiently convey the purpose, usage guidance, and key properties without unnecessary 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?

Given no annotations or output schema, the description adequately covers the tool's purpose, usage, and key behavioral details (recoverability, format). It is missing potential edge cases (e.g., what if section doesn't exist) but is sufficient for its simplicity.

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 has 67% parameter description coverage (section and content are described, findingId is not). The description does not add any additional parameter details beyond what the schema provides, so it meets the baseline but does not compensate for the missing parameter description.

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 explicitly states 'Replace the entire prose under a named section' with a specific verb and resource, and distinguishes itself from the sibling tool konsulto_append_to_section by advising to prefer appending unless rewriting is intended.

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 provides clear guidance: 'Prefer konsulto_append_to_section unless the user explicitly wants to rewrite the section,' directly telling the agent when to use this tool versus an alternative.

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?

No annotations are provided, so the description carries the full burden. It discloses that the body field is omitted, implying a read-only search operation. It does not mention side effects, but the search semantics are clearly non-destructive. Additional details like pagination or ordering are missing, but the essential behavioral trait (returning summary fields) is covered.

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 three sentences long, each serving a purpose: core action, returned fields, use cases. No redundant words. Front-loaded with the primary purpose. Every sentence 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?

Given the complexity (5 parameters, no output schema, no annotations), the description covers purpose, scope, return fields, and use cases. It explains the default audit behavior and the exclusion of the body field. It does not cover sorting, pagination details, or exact match behavior, but the essential information for an agent to decide to invoke the tool is present. Slightly more detail on result ordering could push it to 5.

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 40%, so the description needs to compensate. It adds context for 'audit' (defaults to active audit, matching schema) and 'q' (search across title, matching schema). However, for 'severity', 'status', and 'limit', the description provides no extra semantics beyond what the schema's enums and default value already indicate. Thus, it adds minimal value for these parameters.

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 ('search findings'), the resource ('findings within an audit'), and the scope (defaults to active audit). It enumerates exactly which fields are returned, differentiating it from siblings like konsulto_get_finding which likely returns full details.

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 explicit use cases: 'check for duplicates before creating a new finding' and 'find a specific finding to update or attach evidence to'. While it does not list when not to use it, the context of sibling tools implies alternatives for full retrieval (get_finding) and creation (compose_finding). Clear enough for an agent.

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?

No annotations provided, so description carries full burden. Clearly states returns slim shape and does not return full body. Implies read-only behavior. Minor gaps on search behavior (case sensitivity, pagination) but core transparency is strong.

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. Every sentence adds value 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?

Covers workflow role, return shape, and selection heuristic. Missing parameter usage context but otherwise complete for agent decision-making.

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?

Does not mention any of the three parameters (q, severity, limit). Schema coverage is only 33% (q described), but description adds no parameter guidance. Should compensate for low coverage.

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' and resource 'finding-template catalog'. Clearly distinguishes from sibling konsulto_compose_finding by positioning itself as a precursor step.

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 says 'Use this to pick a template before calling konsulto_compose_finding' and provides selection heuristic. Names the specific sibling tool as follow-up.

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?

Discloses all key behavioral traits: accepts audit ID or name substring with fuzzy match (exact match wins, then unique substring), and that it affects default behavior of subsequent tools. No annotations, but description fully compensates.

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 main purpose, no extraneous details. Every sentence 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?

Given a single required parameter and no output schema, the description covers purpose, usage, matching details, and an alternative. No gaps detected.

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?

Adds significant meaning beyond the schema's parameter description by explaining the fuzzy match behavior, ID vs. name, and the winner rules. Schema coverage is 100%, but description enriches it considerably.

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?

Clearly states it pins one audit as the session's active audit, making subsequent tools default to it. This is a specific verb+resource that distinguishes it from all sibling tools, which are CRUD operations on audits, findings, etc.

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 clear context for when to use (to set active audit for a session) and mentions a recommended persistent alternative (.konsulto.yml). Lacks explicit exclusions, but the context is sufficient.

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?

No annotations provided, so description carries burden. States it updates scalar fields but lacks details on side effects, permissions, idempotency, or whether it's a partial update. Adequate but could be better.

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 concise sentences, each adding distinct value: function, exclusions, and another exclusion. Front-loaded with main purpose. 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 nested patch object, no output schema, and no annotations, description covers main usage and exclusions well. Could clarify that patch only includes fields to update, but overall complete for decision-making. Good differentiation from 18 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 coverage is 0%, but description lists updatable fields (title, severity, status, taxonomy, assets), adding meaning. However, does not explain the 'taxonomy' field structure or that patch is a partial update. Partially compensates for schema's lack of 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 updates scalar fields on an existing finding, listing specific fields (title, severity, status, taxonomy, assets). It distinguishes from siblings by explicitly stating what NOT to use it for, naming alternative tools.

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 guidance on when to use (changing scalar fields) and when not (prose body, evidence), with named alternatives (konsulto_append_to_section, konsulto_replace_section, konsulto_add_evidence_to_finding).

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?

No annotations provided, so description carries full burden. It discloses the return values: user identity, tenant, role permissions, MCP token expiry, active audit pin. It implies a read-only operation with no side effects.

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: first sentence states purpose, second gives usage guidance and output summary. No filler, front-loaded with key info.

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 parameters and no output schema, the description fully explains what the tool does and what it returns. Ideal for a simple status/identity 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?

Input schema has zero parameters, so schema coverage is 100%. Description adds no param info (none needed), baseline 4 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?

Description uses specific verbs ('Show who the MCP is acting as') and clearly identifies the resource (identity, permissions, audit config). It distinguishes from sibling tools that focus on audits, findings, assets, etc., by positioning this as a session orientation tool.

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 states 'Call this first in any session to orient yourself before performing actions.' Provides clear when-to-use context, but no explicit when-not or alternatives (though it's unique, so not necessary).

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