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

No annotations are provided, and the description does not disclose whether the tool is read-only, has side effects, or requires special permissions. It only mentions that it 'provides insight' and 'shows' output, which is insufficient to understand its behavioral footprint.

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 brief and focused: two sentences that state the purpose and output. There is no redundant information or unnecessary fluff, making it easy for an agent to parse quickly.

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

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

Given the tool's simplicity and the presence of an output schema (not shown but indicated), the description covers the essential input and output details. It explains what the tool does, what it returns ('Semantic analysis with entities, relations, and optional logical forms'), and the key parameter options. It lacks mention of error conditions or edge cases, but these are not critical for a straightforward analysis tool.

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

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

The schema fully defines the parameters (text as required string, include_logical_form as optional boolean with default). The description adds a bit of semantic context ('Text to analyze semantically' and 'Whether to include the formal logical representation') but does not go beyond what the parameter names and types imply. Since schema coverage is complete, the baseline is 3, and the description provides minimal extra value.

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 action ('Analyze the semantic structure of text') using a specific method ('Montague Grammar parsing'). It also distinguishes itself from sibling tools like wiki_search, ingest_text, and query_knowledge by focusing on formal semantic analysis rather than retrieval or ingestion.

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 no guidance on when this tool should be used over alternatives. It does not mention any conditions, limitations, or contrasting scenarios that would help an agent decide between this and other 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?

No annotations are provided, so the description carries the full burden of disclosing side effects or behavior. The phrase 'test tool to check if MCP server is working' is vague and does not specify whether it performs any writes, makes network calls, or returns a simple status. This lack of detail fails to accurately convey the tool's behavior.

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

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

The description is a single, concise sentence that directly states the tool's purpose without any extraneous information. It is well-structured and easy to read, earning full marks for conciseness.

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?

While the description is adequate for a simple diagnostic tool, it lacks context about what 'working' means or what the expected output is (e.g., a success message or a boolean). The existence of an output schema is noted but not detailed, so an agent might not fully understand what to expect from invoking this tool.

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

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

The tool has zero parameters, and the schema coverage is 100% (empty). Per the baseline for 0 parameters, a score of 4 is appropriate since there are no parameters to describe and the description does not need to explain any.

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 as a test to check if the MCP server is working, using the verb 'check' and resource 'MCP server'. It is distinct from sibling tools which focus on wiki or synapse operations, so it is easily differentiated. However, it is somewhat generic about what 'working' entails.

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

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

The description implies usage as a diagnostic tool but does not explicitly state when to use it versus other tools. Since all sibling tools have different domains, no direct alternative is obvious, but the absence of explicit usage scenarios leaves some ambiguity.

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, and the description does not explicitly state whether the operation is read-only, has side effects, or requires special permissions. While exploring graph connections implies a non-destructive action, the lack of any transparency about potential rate limits or data access restrictions leaves the agent uncertain.

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 concise and well-structured, with a brief overview followed by a purpose statement and parameter list. The only minor redundancy is the second sentence repeating the concept of 'exploring' from the first, but it adds value by specifying 'non-obvious connections'.

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

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

The description covers the core functionality, parameter meanings, and a general note on returns (visual representation of connections). It does not detail the output schema, but the context indicates one exists, and the tool's moderate complexity makes this absence acceptable. Alternative tools and behavioral details are not addressed, slightly reducing 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?

All three parameters are thoroughly explained in the Args section: entity is the starting point, depth specifies the relationship hops with a range, and connection_types allows filtering by relationship type. This fully compensates for the schema lacking inline descriptions, giving the agent clear semantic meaning for each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool explores connections and relationships around a specific entity in the knowledge graph, using a specific verb and resource. It distinguishes itself from sibling tools like query_knowledge or wiki_search by focusing on graph traversal and discovering non-obvious patterns, though it could be more explicit about the output format.

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 does not provide any guidance on when to use this tool versus alternatives. It fails to mention conditions like 'use this when you need to find relationships' or exclude cases where query_knowledge might be more appropriate, leaving the agent to infer applicability from the purpose alone.

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 bears full responsibility for disclosing side effects, costs, or mutation behavior. It only says the tool 'activates' and 'generates', but does not clarify whether this is a read-only operation, whether it modifies the knowledge graph, or whether 'autonomous' implies background processing or external calls.

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 not excessively long, but it repeats 'autonomous' and 'engine' and phrases the same idea twice. The structure is clear with an action statement, parameter list, and return value, though the redundancy slightly reduces conciseness.

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

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

The tool has a simple input schema with two optional parameters and no nested objects, and the description includes a return summary. However, it does not provide enough context about expected output shape, failure modes, or how the returned insights relate to the knowledge graph, making it only moderately 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?

The schema provides no descriptions, so the description must compensate. It offers minimal explanations for 'topic' and 'confidence_threshold' (e.g., 'focus insight generation' and 'minimum confidence level'), but does not elaborate on how these parameters affect results, what default values do, or how the threshold is applied.

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 action ('Trigger autonomous insight generation') and a specific resource ('Zettelkasten engine'). It also emphasizes generating novel insights from the existing knowledge graph, which helps distinguish it from sibling tools like query_knowledge or explore_connections, though it does not explicitly name 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 does not provide explicit guidance on when to use this tool versus the many sibling tools. It implies usage for autonomous insight generation, but it lacks concrete scenarios, prerequisites, or exclusions that would help an agent choose between generate_insights and alternatives like query_knowledge or analyze_semantic_structure.

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 provided, the description carries the full burden of behavioral disclosure. It does reveal that the tool writes to the Neo4j knowledge graph and triggers insight generation, indicating side effects. However, it does not mention reversibility, idempotency, or failure modes, and the description stops short of outlining any permissions or rate limits.

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 well-structured with a clear purpose statement, numbered pipeline steps, and an Args section. The numbered steps provide a logical flow, but the overall length is slightly verbose—some steps could be condensed without losing meaning. The purpose is front-loaded, which is good.

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 moderately complex with three parameters, one required, and no output schema provided. The description covers the main pipeline and return type, but lacks details on expected text format, size limits, error handling, or the structure of the returned summary. Given that an output schema is declared as present (though not shown), the description could reasonably delegate return details, but it leaves gaps around constraints and edge cases.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by listing each parameter (text, source, metadata) with a short explanation of its purpose (raw text, provenance, additional metadata). This adds meaningful context beyond the schema's type/default information, though the descriptions are brief and do not specify formats 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 ingests and processes text into a knowledge graph via semantic analysis, with a concrete resource and verb. It lists specific pipeline steps (Montague Grammar, entity extraction, Neo4j storage) that distinguish it from generic 'ingest' tools, though it does not explicitly name sibling tools like wiki_ingest_raw or synapse_remember to highlight differences.

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

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

No guidance is provided on when to use this tool versus alternatives. The description explains what it does but lacks any conditional context, such as 'use this for raw text ingestion' or exclusions like 'for structured data, use query_knowledge'. An agent must infer appropriate usage from the resource name alone.

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?

Since no annotations are provided, the description carries the full burden of disclosing behavior. It mentions returning results but does not state whether the operation is read-only or has any side effects, nor does it describe limitations or error behavior.

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

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

The description is concise and well-structured, beginning with a clear purpose statement, followed by a list of arguments and return values. It avoids redundancy and presents information in a logical order.

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

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

The description covers the essential purpose and parameters, but lacks details on usage context, output schema specifics, and edge cases. Given the absence of annotations, some safety and behavior information is missing, leaving the description only partially 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?

The input schema has no descriptions for its parameters, so the description's Args section serves as the sole explanation. It provides brief but meaningful explanations for query, include_insights, and max_results, adding value beyond the bare schema fields.

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 'Query the knowledge graph for facts and insights using natural language' and further specifies it provides the conversational interface to the knowledge base. This concise purpose statement clearly distinguishes the tool from its siblings.

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 does not explicitly state when to use this tool over alternatives like wiki_search or synapse_recall. It only hints at a focus on synthesized insights, but lacks clear guidance on appropriate use cases or exclusions.

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 are not provided, so the description carries the responsibility. It describes the tool's query behavior (surfaces facts, returns ranked list) and implies it is read-only by stating it returns results and does not mention modifications. However, it does not explicitly state that the tool has no side effects or that it does not modify data. For a causal-window query tool, the lack of explicit side-effect disclosure leaves minor ambiguity.

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 well-organized: a one-sentence summary, a technical explanation of the matching criteria, an illustrative analogy, a note on correlation vs causation, and a clear Args list. The analogy adds helpful context but could be considered slightly verbose. Overall, it is concise and each sentence contributes to understanding the tool's function and usage.

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

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

The description covers the tool's purpose, behavior, parameters, and the nature of results (ranked list). Since an output schema exists, the description does not need to detail return fields. It omits edge cases or error handling, but these are not typically required for basic tool invocation. The provided information is sufficient for an agent to decide when and how to use it.

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?

Despite the schema having no property descriptions, the tool description includes an Args section that explains all three parameters: effect_entity (the thing whose causes you're hunting), before (ISO date/datetime when effect was observed), and within_days (how far back to search, with default). This provides both meaning and usage context, fully covering the schema gaps.

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 with a specific verb ('Find candidate causes') and identifies the resource (facts) and the mechanism (temporal correlation, valid_from window, entity sharing). It also distinguishes itself from other tools by explicitly framing the correlation-vs-causation role. This is more specific than a generic 'search' and leaves no ambiguity about what the tool accomplishes.

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 concrete usage scenario ('track everything you ate to find what caused the headaches') and clarifies that the tool returns correlation, not causation, which sets expectations for interpretation. However, it does not explicitly mention alternative tools (e.g., synapse_timeline or explore_connections) or state when not to use this tool. It gives enough guidance for typical use but lacks direct comparisons.

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, but the description discloses key side effects: it sets valid_to rather than deleting, preserves history, affects default queries, and returns the number of affected facts. It does not cover error behavior or idempotency, but the main mutation is well explained.

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 well-structured with short paragraphs for behavior, arguments, and return value. No redundant or extraneous text.

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

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

The description covers the operation, all parameters, the return value, and the semantic implication for queries. It could mention what happens if no matching triple exists, but for a simple invalidation tool the provided context is sufficient.

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?

Every parameter is explained in the Args section: subject/predicate/object form the triple to invalidate, and ended is the ISO date/time defaulting to now. This fully compensates for the empty schema 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?

Clearly identifies the action: invalidating a previously-recorded fact in the knowledge graph by setting valid_to, with the distinction that the historical record remains intact and only default queries change. This differentiates it from query/recall siblings.

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

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

The description implies when to use it ('previously-recorded fact' no longer true) and contrasts with deletion, but does not explicitly name sibling tools or state when not to use it. Still, the intended use case 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 of disclosing behavior. It states the output (count and time span) but does not explicitly declare that the operation is read-only or non-mutating. It also does not mention behavior when no temporal facts exist or any potential side effects. Since it is called 'stats', it likely is read-only, but that is not stated, which is a gap in transparency.

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 short sentence that front-loads the purpose ('Quick stats') and immediately specifies the key outputs. There is no filler or wasted words. It is concise and appropriately structured for a zero-parameter utility tool.

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 that the tool has no parameters, an output schema exists (though its contents are not shown), and the description covers the essential returned metrics (count and time span), the description is largely complete. It does not mention whether the stats are scoped to any subset or if they reflect the entire memory store, but that is likely implicit given no parameters. Minor omission of edge-case behavior (e.g., empty store) prevents a perfect score.

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

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

There are zero parameters, so the baseline is 4 per the scoring rules. The description does not need to add parameter details since there are none. The schema coverage is 100% (empty properties), and the description correctly focuses on what the tool does rather than 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 states the tool returns quick stats about temporal facts (count) and time span. It is specific about the resource (temporal facts) and the output metrics. It distinguishes from sibling tools like synapse_recall or synapse_timeline, which are likely query or retrieval operations, by focusing on aggregate statistics.

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

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

The description implies usage for getting a quick overview of stored temporal facts, but it does not explicitly state when to prefer this over alternatives like synapse_timeline or query_knowledge. No exclusion criteria or context is provided. For a simple stats tool, the intended use is fairly obvious, but the absence of any guidance on alternatives or edge cases leaves room for ambiguity.

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 the full burden. It discloses that the tool returns a newline-separated list of facts with timestamps, and that an empty result means no facts were found, which covers normal behavior. It does not mention error cases, but the read-only nature is implied by 'look up' and 'returns.'

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 tightly organized into Args and Returns sections with no filler. Every sentence adds relevant detail about invocation or output.

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 sufficient to call the tool correctly for common cases: all parameters, defaults, and output format are specified. It lacks examples or error behavior, but those are not essential for this simple lookup 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?

All three parameters are explicitly explained in the docstring: entity matches subject/object depending on direction, as_of is an ISO datetime filtering temporal validity, and direction defines outgoing/incoming/both with its default. This fully compensates for the empty schema 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 looks up time-stamped facts about an entity, using a specific verb and resource. It is distinguishable from sibling tools like query_knowledge or synapse_timeline by focusing on entity-specific temporal facts, though it does not explicitly contrast itself with 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?

No guidance is given on when to prefer this tool over alternatives such as query_knowledge, synapse_timeline, or explore_connections. The description explains mechanics but not use cases or 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?

With no annotations provided, the description carries the full burden. It discloses idempotency ('safe to call twice'), the return value (fact id), default values for confidence and source, and date semantics (bare dates → midnight UTC). This is comprehensive behavioral context beyond what the schema offers.

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 longer than average but well-structured: an opening purpose, a 'Use this when' block, a parameter list, and a return note. Every section earns its place, though it could be tightened slightly without loss of clarity.

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 complex tool with 8 parameters, no annotations, and no schema descriptions, the description covers all essential aspects: purpose, usage context, parameter semantics, defaults, return behavior, and idempotency. Nothing an agent needs to invoke it correctly is missing.

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

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

The schema has 0% description coverage, so the description is the sole source of parameter meaning. It explains every parameter (subject, predicate, object, valid_from, valid_to, confidence, source, note) with formats, defaults, and intended usage. It adds substantial value beyond the schema's bare type definitions.

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 ('record') and resource ('time-stamped fact in Synapse's episodic memory'), with concrete examples of use cases. It clearly differentiates from siblings like synapse_recall, synapse_timeline, and synapse_invalidate by focusing on writing rather than reading or deletion.

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 explicitly says when to use this tool ('whenever something is worth remembering across sessions') and lists categories (decisions, observations, health logs, milestones). It doesn't mention when not to use it or contrast with alternatives, but the context is clear enough for an agent to decide.

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 the full burden. It discloses the ordering ('oldest first') and the entity scoping behavior ('Scope to one entity, or None for the global timeline'). It does not explicitly state that it is read-only, but the word 'view' implies it. It adds useful behavioral context beyond 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?

The description is a compact docstring with a clear opening purpose, followed by parameter explanations and a returns line. Every sentence earns its place; it is front-loaded with the core purpose and contains 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 tool is simple (two optional parameters) and an output schema exists, so the description need not explain return values. It covers both parameters and the ordering behavior, which is sufficient for an agent to call it correctly. It does not mention edge cases or error handling, but these are not critical for a read-only timeline view.

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

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

Schema description coverage is 0%, so the description must fully explain the parameters. It does so: 'entity' is described as scoping to one entity or the global timeline, and 'limit' is described as max rows with a default of 50. This adds meaningful semantics that the schema lacks.

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 'Chronological view of remembered facts' which clearly indicates a specific resource (remembered facts) and a specific behavior (chronological ordering). It is not a tautology and is distinguishable from siblings like synapse_recall or explore_connections by its explicit chronological focus, though it does not explicitly name alternatives.

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

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

The description implies usage when a chronological overview of facts is needed, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it reference any sibling tools. The context is inferred from the wording rather than stated directly.

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. It explains the algorithm (GAAC, TF-IDF), the similarity threshold for merge candidates, and the default behavior for n_clusters, but it does not explicitly state whether the operation is read-only or has side effects. This missing safety information prevents a higher score.

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 concise and well-structured, using bullet points to list the identified outputs. It conveys the necessary information in three short sentences plus a parameter note, 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 presence of an output schema and the relative simplicity of a clustering tool, the description is largely complete. It covers the input parameter, algorithm, and expected outputs. It could mention whether the tool operates on all wiki pages or a subset and whether it modifies data, but these are minor 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?

The input schema only provides the parameter name and type, with no description. The tool description compensates fully by explaining the meaning of n_clusters and its default behavior ('auto = sqrt of page count if omitted'), adding significant semantic value 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 tool's purpose: 'Cluster wiki pages by semantic similarity using GAAC (TF-IDF).' It also enumerates specific outputs (natural topic clusters, missing links, merge candidates), making it distinct from sibling tools like wiki_search or wiki_read_page.

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 does not explicitly state when to use this tool versus alternatives. There is no comparison to sibling tools such as wiki_search or analyze_semantic_structure, leaving the agent to infer the appropriate context from the purpose.

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 the side effects: fetching a URL, saving to raw/, ingesting into Neo4j, and archiving to Clippings/. It also explains the conditional behavior of the ingest parameter, but it does not mention permissions or reversibility.

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 tight and structured: one pipeline sentence, one usage sentence, then a short Args list. There is some repetition of the ingest behavior in both the pipeline and parameter sections, but it is not padded or confusing.

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

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

An output schema exists, so return values are not a missing piece. The description covers the main flows: default full ingestion and ingest=False partial save. Omitting prerequisites like public reachability or the relationship to sibling tools is a minor gap, not a blocking one.

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

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

The schema has 0% description coverage, so the description must convey parameter meaning, and it does. 'url: The URL to fetch and process' is sufficient, while 'ingest' explains the default True behavior and explicitly says that setting False saves to raw/ for manual review first. This goes well beyond the schema's bare types and default.

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 pipeline — 'Fetch a URL with defuddle (clean markdown extraction), save to raw/, ingest into the knowledge graph, and archive to Clippings/' — so the action and resources are concrete. It also contrasts with 'raw web_fetch', helping to differentiate the tool, though that particular alternative is not in the sibling list.

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?

'Use this when researching the web — it strips navigation and clutter' is explicit about the intended use case, and 'Much cleaner than raw web_fetch' names a comparison point. However, it does not say when not to use this tool nor how to route between this and sibling tools like wiki_ingest_raw.

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 present, so the description carries the burden of explaining behavior. It explains what the scores mean and how to interpret them, but it does not explicitly state whether the tool is read-only or if it has any side effects on the wiki graph. This leaves some ambiguity.

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 well-structured: a single defining sentence followed by two clarifying sentences that explain the output interpretation and usage. No redundant or irrelevant content.

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

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

For a tool with no parameters, the description adequately covers purpose and interpretation of results. It could mention the output format or whether scores are normalized, but this is not essential for an agent to decide when to use the tool.

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

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

The tool has no parameters, so there is no parameter information to add. The description does not need to clarify inputs, and nothing is missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Compute HITS hub and authority scores') and the precise subject ('wiki wikilink graph'), distinguishing it from sibling tools like wiki_search or wiki_cluster_pages.

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 concrete use cases: identifying pages needing deepening (high authority) and pages needing comprehensive link coverage (high hub). It does not explicitly name alternatives, but the usage guidance is clear enough for an agent to decide when to invoke this 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?

With no annotations, the description carries the full burden. It transparently discloses that the operation writes to both Neo4j and a wiki page, and details the pipeline. It does not mention idempotency, error handling, or permissions, but the core write behavior is clear. This is adequate for a single-step ingestion tool.

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 tight sentences plus an args line, with the core purpose front-loaded. Every sentence earns its place—purpose, pipeline steps, and parameter clarification—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?

The description is complete for a single-parameter tool with an output schema. It covers the input location, the transformation steps, the output locations, and the parameter semantics. An agent can invoke it correctly without additional 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?

The description adds meaning beyond the schema by specifying that 'filename' refers to a file inside the raw/ directory, which the schema's bare 'Filename' does not convey. For a single parameter, this is sufficient context, though it could be more explicit about accepted formats or extensions.

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 action ('ingest a raw source file') and its destinations (knowledge graph and wiki), with concrete steps (reads from raw/, runs Synapse pipeline, stores in Neo4j, creates summary page). This distinguishes it from siblings like ingest_text and wiki_write_page, which target different inputs or outputs.

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

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

The description implies the tool is for files in the raw/ directory, which is a usage context. However, it does not explicitly compare with alternatives (e.g., ingest_text for direct text, wiki_write_page for manual page creation) or state when not to use it. This leaves some ambiguity for an agent choosing between similar tools.

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

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

The description implies a read-only operation ('health check') but does not explicitly state that the tool makes no modifications or side effects. Given the absence of annotations, the description carries the full burden but leaves the behavioral guarantees somewhat vague.

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 highly concise—only two sentences—and avoids unnecessary words or repetition. It front-loads the action ('Run a health check') and lists the key detection capabilities efficiently.

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 provides enough context for an agent to understand the tool's scope and trigger appropriate usage. It does not mention output format or return details, but for a zero-parameter health check, this omission is minor and does not hinder 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 tool takes zero parameters, so there is nothing to describe. With no parameter list, the baseline of 4 applies, and the description correctly omits any irrelevant parameter details.

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: running a health check on the wiki vault and explicitly lists the specific issues it detects (orphan pages, broken wikilinks, missing frontmatter). This distinguishes it from all sibling tools, which focus on other operations like search, memory, or URL fetching.

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 makes the intent obvious, so an agent knows when to use this tool (when a wiki health check is needed). While it doesn't explicitly contrast with alternatives, no sibling tool offers a similar linting/health-check function, so the guidance is implicitly 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions pagination and subdirectory choices, but does not disclose ordering, whether it returns full page content or just metadata, rate limits, or any side effects. The description gives only minimal behavioral context beyond the bare listing operation.

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

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

The description is concise and front-loaded with the purpose statement. The Args block is a compact, standard format that efficiently covers all parameters. It could be slightly more structured, but it contains no waste and is easy to scan.

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

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

An output schema exists, which lightens the burden of explaining return values. However, the description still lacks details on pagination behavior (e.g., whether offset is zero-based, how total count is conveyed), error handling, or whether the listing is alphabetical or by some other order. For a tool with no annotations, this is a notable gap, but the output schema and simplicity of the operation keep it from being severely incomplete.

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

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

The schema has zero descriptions (0% coverage), so the description must compensate. It does so by explaining each parameter: subdir ('wiki' or 'raw'), limit (default 50, max 200), offset (pagination), and tag (filter). This adds meaningful semantics that the schema lacks, making parameter usage clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List all markdown pages in the wiki vault with pagination.' This clearly conveys the core operation and scope. However, it does not explicitly differentiate from sibling tools like wiki_search or wiki_read_page, though the verb 'list' and pagination hint at distinctiveness.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios where wiki_search would be more appropriate, nor any exclusions or prerequisites. The description only states what it does, leaving usage context entirely to inference.

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

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

The description makes clear this is a read operation and notes whether each mode reads from disk or an index, which gives some behavioral transparency. However, with no annotations, it does not mention error cases, missing paths, or permissions.

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 concise and well organized, using a short intro and bullet-like lines for mode values. No unnecessary words or redundant 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?

The description provides enough to invoke the tool with correct parameters and understand the mode options, but does not discuss return format, potential errors, or how it relates to sibling read/search tools. Since an output schema exists, the lack of return detail is acceptable, but some contextual guidance 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?

Both parameters are covered in the description: path is defined as relative to the vault root, and mode lists all three accepted values with their return behavior. This adds meaningful detail beyond the bare 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 reads a wiki page, and the mode parameter specifies the level of content to return. It is distinct enough from sibling tools like wiki_search and wiki_list_pages, though it does not explicitly contrast 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 explains the three modes and their performance implications, but does not explicitly state when to use this tool versus alternatives such as wiki_search or wiki_list_pages. Usage context is implied rather than stated.

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

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

No annotations are present, so the description should disclose side effects, permissions, or rate limits. It only explains the search functionality and parameters but does not mention whether it is read-only, modifies data, or requires any special access. For a search tool, it is likely safe, but this is not stated, leaving transparency lacking.

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 concise, uses a clear docstring format with an 'Args' section, and each sentence serves a purpose. It is well-structured and easy to parse, with no fluff or redundant 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?

The tool has a simple search function, and the description covers its purpose and parameters. An output schema is present, so return values need not be described. However, it does not mention potential error conditions or pagination behavior beyond the limit parameter, which would be nice but is not strictly necessary for this simple tool.

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

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

The description comprehensively explains all three parameters: query as space-separated terms, limit for maximum results with a default, and subdir for scoping. This adds meaning beyond the bare schema definitions, which have no descriptions. The coverage is complete and helpful.

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: 'Search wiki pages by keyword.' It uses a specific verb and resource, distinguishing it from sibling tools like wiki_read_page or wiki_list_pages. The action is unambiguous and matches the tool name.

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 explains what the tool does but does not explicitly state when to use it over alternatives, such as against wiki_hits_analysis or wiki_cluster_pages. However, the tool's straightforward search function and the distinct names of siblings make the use case reasonably implicit. No explicit 'use when' or 'don't use when' guidance is provided.

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 the tool is automatic on certain events and explains the manual invocation scenario, but it does not mention any potential side effects such as whether it overwrites in-memory changes or if it is safe for concurrent calls. Since there are no annotations, this lack of explicit safety details leaves some behavioral transparency gap.

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 the first sentence stating the action and the second providing the context for manual use. It is concise, front-loaded, and contains no redundant 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?

For a simple index refresh tool, the description fully covers its purpose, automatic behavior, and manual invocation scenario. It also includes examples of external changes (Obsidian edits, git pull) that warrant a manual call, making the tool's context clear without needing to explain return values since an output schema is present.

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

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

There are no parameters, so the schema fully covers all inputs. The description does not need to add parameter information, and it does not introduce any ambiguity about expected inputs.

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 as refreshing the wiki index database from disk, using the specific verb 'refresh' and identifying the resource. It also provides a condition for manual invocation (files changed outside Synapse), which helps distinguish its intended use from other tools that might modify the index.

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 explicitly states that the tool runs automatically on server start and after write operations, and advises calling it manually only when files were changed outside Synapse (e.g., Obsidian edits, git pull). This gives clear guidance on when to use it versus relying on automatic triggers, and hints that it should not be called manually for normal Synapse updates.

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 must disclose side effects and behavior. It states that the tool rebuilds the index and optionally performs disk-level verification, but it does not mention whether the operation is destructive, overwrites existing data, or has performance implications. This lack of detail reduces transparency.

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 concise and well-structured, with a one-sentence purpose followed by a clear parameter explanation. No unnecessary words or redundant information are present.

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 tool, the description covers the core action and parameter. However, it lacks critical context about side effects, relationship to similar sibling tools (e.g., wiki_sync_index), and potential use cases. This leaves some gaps for an agent deciding whether and how to invoke it.

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 single parameter 'deep' is clearly explained in the Args section: 'If True, performs a disk-level verification of all indexed files.' This provides sufficient semantic meaning beyond the raw schema, which contains no description for the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: rebuilding the wiki index from all wiki pages. The verb 'rebuild' and resource 'wiki index' are specific. However, it does not distinguish itself from the similarly named sibling 'wiki_sync_index', which may cause ambiguity.

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 no explicit guidance on when to use this tool versus alternatives such as wiki_sync_index or wiki_lint. It mentions rebuilding from all wiki pages and the deep flag, but leaves the decision-making to the agent without context on appropriate scenarios.

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 the full burden for behavioral disclosure, but it only says 'write or update' and mentions frontmatter. It does not state whether existing pages are overwritten or merged, whether parent directories are created, or what happens to existing frontmatter fields.

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 extremely concise, with a single opening sentence followed by a compact argument list. No unnecessary text is present, and the core purpose is front-loaded.

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 write tool the description is mostly adequate, and the output schema presumably covers return values. However, the relationship between summary/tags and the frontmatter is left implicit, and the tool's behavior relative to the wiki index and other siblings is not clarified.

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 Args section provides meaningful descriptions for all four parameters, including an example for path and clear statements for body, summary, and tags. Since the schema has no descriptions, this compensates well, though body constraints could be more detailed.

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 identifies the action (write or update), the resource (wiki page), and a key feature (frontmatter). It does not explicitly distinguish from sibling tools like wiki_update_index or wiki_ingest_raw, but the focus on page-level writing is evident.

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

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

No guidance is provided about when to choose this tool over alternatives or what scenarios call for it. There is no mention of not using it for index updates, bulk ingestion, or other related operations.

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