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

Annotations already mark readOnly, idempotent, and non-destructive, and the description confirms 'Read-only operation'. It adds value by disclosing what the analysis examines (semantic meaning, value differences, numeric/temporal ranges, contextual dimensions) and what it returns, which an agent cannot infer from annotations or schema alone.

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

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

Three sentences front-load the action, follow with the analytical scope, and end with the return payload. There is no filler, and every clause adds 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?

With a full output schema, complete parameter descriptions, and safety annotations, the description is nearly complete for invocation. A small gap is the lack of any statement about prerequisites or error behavior (e.g., claims must already exist), but this is minor given the structured data.

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%, so the descriptions of claimAId, claimBId, and explainContext already carry full meaning. The tool description adds no parameter-specific detail beyond the generic notion of comparing two claims; 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?

The description opens with 'Performs deep comparative analysis between two factual claims' – a specific verb and resource that immediately distinguishes it from the single-claim accessors (claims.get/list) and the conflict-oriented siblings. It further narrows the output to contradiction classification, severity, confidence, and explanation, so an agent can select it without examining the schema.

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

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

It gives a clear invocation context: pass two claim IDs and receive a contradiction assessment. It never names alternatives or states when not to use it, so it stops short of the explicit routing of a 5, but the context is unambiguous.

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 carry readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description redundantly states 'Read-only operation' and describes return content, but adds no additional behavioral disclosure such as auth requirements, rate limits, or error behavior. No contradiction with annotations.

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

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

A single front-loaded sentence states the core action, followed by a dense list of return components. No filler, redundant modifiers, or digressions. Every phrase 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?

The description covers purpose, scope, and return contents. With annotations declaring safety and idempotency, schema covering both parameters, and an output schema present, the description provides all necessary information for correct invocation of this simple read-only 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 description coverage is 100%, so both claimId and includeHistory are already fully documented. The description's mention of 'by ID' and 'chronological historical value transitions' aligns with these parameters but adds little beyond the schema. 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?

The description states the exact action ('Retrieves complete details for a single factual claim by ID') and enumerates the returned content. By emphasizing 'single... by ID', it clearly distinguishes itself from sibling list tools like contradiction.claims.list, making the tool's scope immediately 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?

The phrase 'by ID' implies the tool is for retrieving one known claim rather than listing or scanning, but no explicit alternatives or exclusions are provided. An agent must infer when to use it versus claims.list or claims.analyze, so the guidance 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), and the description's 'Read-only operation' merely restates that. It does add that the data comes from connected sources and that filtering is flexible, but otherwise leaves pagination/behavioral details to the 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?

Two compact sentences front-load the core purpose, state the safety property, and give example use cases without filler. 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 output schema and strong annotations, the description gives enough context on purpose and typical use. It could mention when to choose list over claims.get, but this is a minor gap given the schema captures the rest.

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 every parameter has a description, so the baseline is 3. The description adds a summary of filterable dimensions but no new parameter-level semantics 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?

States a clear verb and resource ('Queries stored factual assertions and claims...') and names the filtering dimensions, making the listing purpose obvious. It does not explicitly contrast with siblings like claims.get or claims.analyze, so it stops short of full differentiation.

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 usage context ('explore known facts, find subjects with multiple assertions, or inspect extracted data'), which signals typical scenarios. It doesn't name alternatives or exclusions, so an agent must infer when to prefer the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this with 'Read-only deterministic calculation' and adds the deterministic behavior, which is beyond the annotations. It also discloses the analytical dimensions (authority, freshness, evidence) without contradicting any annotation.

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, information-dense sentence that front-loads the core function and then states the recommendation output and read-only nature. It is efficient, though the phrase 'advisory' and 'remediation steps' could be slightly tightened without losing meaning.

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 (one parameter, no nested objects), the schema is fully described, annotations cover safety/idempotence, and an output schema exists. The description supplies the decision-making purpose and deterministic/read-only nature, which is sufficient context 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 description coverage is 100%, and the sole parameter 'contradictionId' is already documented in the schema with 'The unique ID of the contradiction record to analyze for resolution advice'. The description adds no additional parameter-specific meaning, so the baseline of 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?

The description clearly states a specific verb ('Generates') and resource ('authority, freshness, and evidence comparison between conflicting claims') with a concrete goal: advising which claim likely represents current truth and remediation steps. This distinguishes it from siblings like contradiction.conflicts.resolve (which implies mutation) and contradiction.conflicts.get (which only retrieves).

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 context is clear: use this tool when conflicting claims need authority/freshness/evidence comparison and advisory recommendations. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can infer when to choose it over siblings, especially the non-mutating 'resolve' sibling.

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, and destructiveHint=false, and the description's 'Read-only operation' aligns with these. It adds value by describing the full contents of the returned record, including the chronological audit trail, which clarifies the includeAuditHistory parameter's effect. No contradictions with annotations.

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

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

The description is one dense, focused sentence plus the phrase 'Read-only operation.' Every element earns its place: the resource, the ID-based access, the key payload components, and the safety indicator. There is no fluff or repetition.

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

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

The description covers all essential aspects for a read-only getter: what the resource is, how it is accessed, and what the response includes. An output schema exists, so return-value structure is captured elsewhere. It lacks explicit routing to sibling tools, but for a simple retrieval operation with strong annotations and parameter documentation, it is adequately 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 100%: contradictionId and includeAuditHistory are both clearly documented in the schema. The description's mention of the audit trail echoes the parameter but does not add new syntax or semantic detail beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation 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?

The description states a specific verb ('Retrieves') and a precise resource ('a single contradiction record by ID'), and enumerates exactly what is included: both claims, source metadata, line evidence snippets, and the audit trail. This distinguishing detail separates it from list/scan siblings, so an agent knows exactly what this tool does.

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 conveys that the tool is for fetching a single record once an ID is known, but it does not explicitly state when to use this over conflicts.list (e.g., for browsing) or conflicts.resolve (for mutations), nor does it mention any exclusions. Usage context is implied rather than articulated.

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, and destructiveHint=false, so the description's 'Read-only operation' is redundant. It adds some context by specifying the data is 'stored' and 'enriched,' but does not disclose pagination behavior or other operational traits beyond what annotations cover.

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 front-load the core querying purpose, then describe the output, confirm read-only behavior, and close with the intended use case. Every sentence contributes value with 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?

The schema fully documents parameters and enums, an output schema exists for return values, and annotations cover safety. The description adds the usage context and enrichment details, making the tool fully understandable for an agent.

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%, so the schema already documents all six parameters. The description summarizes the filter dimensions but adds no new parameter-level detail beyond what the schema provides, 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 states a specific verb ('Queries'), a resource ('stored contradiction records'), and the exact filtering dimensions (status, severity, type, confidence). It also clarifies the returned shape (enriched records with claim summaries and source details), which distinguishes it from sibling tools like conflicts.get and conflicts.scan.

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 use: 'Use this tool to prioritize and triage conflicts.' It does not explicitly state when not to use it or name alternatives, but the purpose context is clear and sufficient for a query/list 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 convey mutating/non-read-only behaviorholley and idempotency. The description adds valuable context by stating that the audit trail is immutable and preserved, and by explaining the semantics of each status transition. This goes beyond what annotations alone 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 compact and front-loaded with the core purpose. Every clause adds at least one meaningful distinction, though the closing 'Mutating operation' is somewhat redundant with the annotations and the opening verb.

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 7-parameter lifecycle tool, the description covers all action types and important behavioral commitments such as the immutable audit trail. Schema and output schema cover the remaining parameter and return details, so nothing critical 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 description coverage is 100%, so the baseline is 3. The description adds meaning by linking actions to the authoritative chosen claim, acceptable divergence, reviewer identity, decision reason, and timestamp, which helps an agent understand which parameters are relevant for each action.

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 clear verb and resource: 'Updates the lifecycle status and audit trail of a contradiction record.' It then enumerates the full set of supported transitions, distinguishing this mutating lifecycle tool from read-only siblings like contradiction.conflicts.list and contradiction.conflicts.get.

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 clearly scopes the tool to lifecycle/state changes, which is sufficient context for choosing it over read/scan/advise siblings. It does not explicitly name alternatives or exclusions, but the action set makes the intended usage obvious.

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 key behavioral traits beyond the annotations: it uses deterministic candidate grouping, entity resolution, and value comparison algorithms; it persists contradictions; it avoids duplicates; and it is idempotent. The annotations already declare idempotentHint=true and destructiveHint=false, and the description reinforces and expands on this by explaining the mutating-but-idempotent nature. It doesn't mention rate limits or auth, but for this tool the algorithmic and persistence behavior is the most important context.

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

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

The description is compact and front-loaded: it states the core purpose in the first sentence, then scoping options, then algorithmic behavior, then the mutating/idempotent trait. Every sentence earns its place, and the most important information (what it does) comes first.

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 is complete for a scan tool with 5 optional parameters, full schema coverage, and an output schema. It explains the algorithm, persistence, deduplication, and idempotency. The only minor gap is that it doesn't describe the output format, but the output schema exists, so the description needn't explain return values. A 4 is appropriate because it covers the behavioral context well without being exhaustive.

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%, so the schema already documents all 5 parameters. The description adds context about scoping (source, file, or single claim) that maps to sourceId and claimId, but doesn't add significant detail beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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: discovering conflicting and inconsistent factual assertions across connected sources. It specifies the resource (contradictions), the action (scan), and the scope options (entire database, specific source, file, or single claim), which distinguishes it from sibling tools like contradiction.conflicts.list (which lists existing conflicts) and contradiction.conflicts.resolve (which resolves them).

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

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

The description provides clear context on when to use this tool: when you need to discover contradictions across sources, with optional scoping to a source, file, or claim. It doesn't explicitly name alternatives or exclusions, but the scoping options and the contrast with sibling tools (list, get, resolve) imply the usage context. A 4 is appropriate because it gives clear context but doesn't explicitly say 'use this instead of X when...'.

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 goes beyond the read-only and idempotent annotations by specifying what the check covers (database connectivity, storage metrics, connectors, runtime diagnostics) and adding that it is safe for repeated invocation. The 'Read-only' phrasing echoes the annotations but does not contradict them and contributes useful operational context.

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 redundancy: the first states the tool's core function and scope, the second adds usage guidance. The information is front-loaded and every phrase contributes 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?

For a one-optional-parameter read-only health check with a rich output schema, the description fully covers what the tool does, what it checks, and when to use it. The output schema handles return values, and none of the sibling tools relate to health checks, so nothing essential 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 only parameter (verbose) is fully described in the schema with its purpose, example values, and default. The tool description adds no additional parameter semantics, but it does not need to because the schema already carries the full 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?

The description uses a specific verb ('Checks') with a clearly defined resource ('operational status of the Contradiction MCP server') and enumerates exact aspects of that resource (SQLite connectivity, storage metrics, active connectors, runtime diagnostics). This clearly distinguishes it from sibling tools that focus on conflicts, sources, and claims.

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 usage context: it is 'safe to invoke frequently for readiness and liveness probing.' It does not name alternatives or exclusions, but among the given siblings there is no other health-check tool, and the guidance is clear enough to select it when probing server status.

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, and destructiveHint=false, so the safety profile is covered. The description adds that it is a read-only operation and includes synchronization timestamps and claim counts, which gives useful behavioral context beyond the annotations. It doesn't contradict annotations.

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

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

The description is two sentences with no wasted words. It front-loads the core purpose, includes the read-only note, and ends with a practical usage directive. 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?

The description is complete for a read-only list tool with a rich output schema and full parameter documentation. It could have mentioned pagination behavior or default limit, but the schema already covers those. The usage context (before scans/sync) adds completeness.

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%, so the schema already documents all three parameters (type, limit, offset) with descriptions. The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline 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 tool lists registered external data source connectors and ingested source entities, with specific examples (document, website, github) and details like source IDs, timestamps, and claim counts. It distinguishes itself from siblings by focusing on sources rather than conflicts, claims, or health.

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 to use this tool to inspect available data sources before initiating scans or synchronization, which provides clear context. It doesn't explicitly name alternatives or when not to use it, but the sibling names and the stated purpose make the usage context 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?

Annotations already declare readOnlyHint false, idempotentHint true, and openWorldHint true. The description adds beyond annotations by noting it triggers automatic contradiction discovery, supports concurrent batch with failure isolation, and extracts claims with exact line provenance. It repeats 'idempotent' but this is consistent with annotations. No contradiction.

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 and front-loaded with the main purpose. However, the second sentence 'Mutating and idempotent operation' is redundant with the annotations and does not earn its place given the rule against repeating structured data. Still compact and well-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?

The tool is complex with 11 parameters and nested objects, but the schema and output schema fill most gaps. The description covers overall behavior, external source types, batch capability, and side effects. It does not discuss return format, but an output schema exists, so that is not required. 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?

Schema description coverage is 100%, so all 11 parameters are already documented. The description reinforces connector types (document, website, github) and batch mode, but does not add meaning beyond what the schema provides. Baseline 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 states a specific verb and resource: ingests and synchronizes external data sources, extracts factual claims with exact line provenance, updates SQLite storage, and triggers contradiction discovery. This clearly distinguishes it from siblings like sources.test (testing) and conflicts.scan (scanning) by focusing on ingestion and synchronization.

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

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

The description provides clear context that this tool is for ingesting/synchronizing external sources, including single and concurrent batch modes. However, it does not explicitly state when not to use it or name alternative tools like sources.test or sources.list, so no exclusions are provided. The context is clear but lacks explicit comparison to siblings.

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, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by explicitly stating it 'does not persist any data or modify state' and that it validates connectivity, authentication, and accessibility. This goes beyond the annotations by clarifying the non-mutating nature in operational terms. It doesn't describe error behavior or return format, but the output schema exists and the annotations carry the safety burden, so a 4 is appropriate.

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 with no wasted words. The core purpose is front-loaded ('Validates connectivity, authentication, and accessibility'), followed by the key non-mutating constraint and a clear usage directive. 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?

For a validation tool with 3 parameters, full schema coverage, an output schema, and strong annotations, the description is nearly complete. It covers what the tool does, when to use it, and what it does not do. The only minor gap is that it doesn't describe what happens on failure (e.g., error codes or return structure), but the output schema likely covers return values, and the annotations cover safety. A 4 is appropriate given the strong context signals.

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%, so the schema already documents all three parameters (connector, target, branch) with descriptions and enums. The description adds context about what the parameters mean in practice (e.g., 'owner/repo' for GitHub, URL for website, file path for document) but this largely mirrors the schema. The description does not add significant new meaning beyond the schema, so the baseline 3 is correct.

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 ('validates') and resource ('external data source or connector'), and explicitly names example targets (GitHub repository, web URL, local file). It also distinguishes itself from synchronization by noting it does not persist data or modify state, which helps differentiate it from sibling tools like contradiction.sources.sync.

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 when to use this tool: 'Use this tool to verify credentials and target reachability prior to running synchronization.' This provides clear context and implies the alternative (synchronization) without needing to name a specific sibling. It also states what it does not do (no persisting data or modifying state), which helps an agent decide between this and mutation-oriented siblings.

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