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

Despite no annotations, the description discloses key behavioral traits: live data fetch, output includes a 'truncated flag', and zero_match_diagnostics behavior when no rows match. It also explains condition grammar and having filter semantics with an example, providing substantial 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 dense but well-structured with line breaks, and each sentence adds necessary information (operations, parameters, single-file constraint, diagnostics). It is slightly long but avoids redundancy and earns its length.

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

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

Given the complexity (8 params, grouped aggregation), the description covers essential context: multi-file exclusion, column names source, condition/having grammar, return flags, and error diagnostics. An output schema exists, so return details need not be repeated. Folder_path is the only minor omission, but optional and less critical.

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 carries the burden. It explains group_by (column name or list), conditions (filter_sheet grammar), having (post-aggregation filter with example), and lists operations. However, folder_path and file_name/sheet are not explicitly described, leaving minor gaps for those parameters.

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

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

The description clearly states the tool's core action: 'Fetches a sheet LIVE and runs a grouped aggregation' and lists supported operations. It also distinguishes itself from siblings by explicitly limiting to a single file and pointing to cross_file_aggregate for multi-file operations.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'SINGLE FILE ONLY' and 'For totals across multiple files you MUST use cross_file_aggregate instead'. It also references filter_sheet grammar for condition syntax and advises fetching column names from get_workspace_graph first.

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?

Given no annotations, the description discloses key behaviors: parallel fetching, exact sheet-name matching, listing unmatched files with did_you_mean candidates, and never silently including them. It also warns that warning/skipped_files/unmatched_files indicate incomplete totals and mandates surfacing them to the user. It does not explicitly state read-only nature, but there are no mutations implied.

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 with bolded headings and lists, making it scannable. Each sentence carries actionable guidance, though some redundancy exists (e.g., repeated emphasis on showing per-file breakdown). Overall, it earns its length without being bloated.

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 an output schema, so return values need not be described, yet the description references response fields (unmatched_files, skipped_files, warning) for error handling and gives a cross-tool prerequisite. It does not explain all parameters or link to filter_sheet's conditions structure, but it is highly comprehensive for a complex tool.

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

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

Schema coverage is 0%, so the description must compensate. It clarifies that `sheet` must match exactly and mentions 'filter conditions' conceptually, but it does not explain `value_col`, `operation` options, `conditions` structure, or `folder_path`. It adds some semantic context beyond the bare schema but leaves significant parameter 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 opens with 'MANDATORY for any total spanning more than one file' and explicitly states it fetches sheets from all files, applies filter conditions, and returns the aggregate total. It distinguishes from siblings like filter_sheet and aggregate by contrasting its cross-file scope with single-file 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?

Provides an explicit 'WHEN YOU MUST CALL THIS' list (any cross-file total/sum/count/average, cross-file comparison, verifying totals) and a 'NEVER calculate' list (adding filter_sheet results, Python summing, guessing). It also instructs to check sheet_name_variants in get_workspace_graph first, naming a prerequisite 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 discloses that computation is done in pandas, includes a per-component breakdown with rows_matched, and flags zero-match components with a warning. It does not explicitly state that the operation is read-only (no file modification), but given its nature and the context, that is a minor omission. Overall, it provides strong behavioral safeguards beyond a simple summary.

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 but rich. It front-loads the core purpose, then provides an example, breaks down the components structure, and adds a critical warning. A few words are slightly repetitive ('one call' appears twice), but each sentence adds value and the structure is logical, so it earns a high score without being overly verbose.

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 7 parameters and is genuinely complex, but the description covers the main behavioral contract: the net computation, component structure, optional conditions, and output warnings. It doesn't elaborate on folder_path or file_name, but those are self-explanatory. Given the output schema exists (per context signals), the description does not need to explain return values in detail. This is fairly complete for a tool of this complexity.

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

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

Schema coverage is 0%, so the description is the only source of parameter meaning. It thoroughly explains the complex 'components' list (conditions, sign, label), clarifies 'conditions' as optional pre-filter, and ties 'quantity_col' to the groupwise_sum. This goes well beyond the bare schema and compensates entirely for the lack of 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 uses a specific verb ('Computes') and clearly defines the resource ('NET value over transaction types'). It explicitly contrasts with filter_sheet by showing how it replaces five calls, which strongly distinguishes it from siblings. This is a textbook example of purpose clarity.

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 states when to use this tool: to compute a net figure from signed components in one call, and tells the agent to avoid multiple filter_sheet calls (citing RULE 3). It names the alternative filter_sheet and implies that the tool is the right choice for this pattern. No exclusion criteria are missing; it is very 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?

With no annotations, the description takes full responsibility for behavioral disclosure. It covers the live/cache behavior, case-insensitive normalized matching, exact_case flag, literal-contains semantics, error behavior for unknown columns/operators, zero_match_diagnostics, and the 1000-row limit with truncated/total_matched 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 long but earns its length: a clear purpose sentence, structured condition formats with examples, then matching semantics and edge-case behavior. Each section serves a distinct need, and examples are concrete.

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 seven parameters, nested conditions, and an output schema, this description covers the high-risk behaviors: error semantics, matching rules, zero-match diagnostics, and response truncation. The presence of an output schema covers return-value structure, and the description supplements it with total_matched/truncated details. The only gaps are sort_by/folder_path semantics, which are minor.

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, thoroughly, for the conditions parameter: exact/contains/comparison/date/IN/between/is_null/contains object forms, AND semantics, and normalization. It also explains exact_case and limit behavior. However, sort_by and folder_path are not explicitly described beyond the schema, a minor gap.

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

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

The description opens with a specific verb-resource pair: 'Fetches a specific sheet LIVE from OneDrive and returns rows matching the given conditions.' It also preempts sibling confusion by noting to get column names from get_workspace_graph first and stating 'Use when you already know which file and sheet to query.'

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 'Use when you already know which file and sheet to query,' and directs users to get_workspace_graph for column names, setting clear context. It doesn't spell out when not to use it relative to query/aggregate/join_sheets, but the specificity of the condition syntax and the mention of the 1000-row limit imply boundaries.

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

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

With no annotations, the description carries full burden. It discloses that it reads exactly one cell, performs a live Graph request, converts serial dates to ISO-8601 with a resolved_type check, and treats multi-cell addresses as errors. These are concrete behavioral details beyond a simple read hint.

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 earn their place: purpose, usage, then parameter and behavior details. Front-loaded and free of fluff.

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

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

Given the tool's simplicity and the presence of an output schema, the description covers all key aspects: exact behavior, usage context, parameter semantics, and an edge case. No critical gaps for an AI agent to select and 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?

Schema coverage is 0%, so the description must compensate. It thoroughly explains the address parameter (A1 notation or named range) and its constraints, though file_name, sheet, and folder_path rely on their naming for meaning. Adds clear value for the most complex parameter.

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

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

The description states a specific verb ('Reads'), a precise resource ('EXACTLY ONE cell'), and key qualifiers ('LIVE, by address'), distinguishing it from sibling range tools like filter_sheet. It emphasizes 'no ambiguity' to set expectations.

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 when to use the tool: 'when the location is already known' for follow-up questions or scheduled routines, and names filter_sheet as the alternative for ranges. This provides a clear when-to-use vs when-not-to.

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 and does so thoroughly. It discloses caching ('makes no API call', 'Reads from local graph.json'), warns about unconfirmed layout_confidence, explains multi-region sheets and the risk of summing separate tables, and notes sheet_name_variants as a matching caveat.

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 front-loaded with the core function and all sentences add behavioral value. However, it is somewhat verbose and contains overlapping usage advice ('ALWAYS call this first' and 'Use this before any filter_sheet call'), so it is not maximally concise.

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 exceptionally complete for a tool with an output schema and no annotations. It covers the return content, performance characteristics, caching path, confidence scoring, multi-region quirks, and recommended invocation order, leaving little ambiguity about the tool's role.

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 defines one parameter, folder_path, but the description never mentions it. Schema description coverage is 0%, and the description provides no compensation—an agent would not know when or why to provide folder_path, or what happens if omitted.

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 ('Returns') naming a clear resource ('cached file structure') and enumerates exact content (filenames, sheet names, column headers, cross-sheet relationships). It also distinguishes itself from siblings by highlighting that it is cached and requires no API call.

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?

Explicit guidance is given: 'ALWAYS call this first at session start' and 'Use this before any filter_sheet call when unsure which file or column to query.' This makes the intended usage context and sequencing very 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?

With no annotations, the description fully discloses behavior: it 'makes no API call', 'reads from cached graph.json', and the count is 'not live' and should be treated as an 'order-of-magnitude hint'. This reveals staleness and performance characteristics beyond what annotations would provide, ensuring the agent understands the tool's limitations.

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, front-loaded with the primary purpose, and every sentence earns its place: it covers the output, the caveat about non-live counts, the performance characteristic (INSTANT), and a usage example. No fluff or 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 provides rich behavioral context (caching, staleness, speed) and usage guidance, and an output schema exists to detail return values. However, the folder_path parameter is not explained, and the description does not mention potential error cases or prerequisites. These gaps are minor given the tool's simplicity.

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

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

Schema description coverage is 0%, so the description must explain parameters. It implicitly covers file_name via 'one specific file', but it does not mention folder_path at all. This leaves one of two parameters unexplained, which is a significant gap in parameter semantics.

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

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

The description clearly states the tool's purpose: 'Returns structural metadata for one specific file — sheet names, column headers, and each sheet's approx_row_count.' This is specific with a verb ('returns') and resource ('one specific file'), and it distinguishes the tool from siblings by emphasizing structural metadata and its use before filter_sheet.

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 advises 'Use before filter_sheet when you need to confirm the exact column names available in a specific file.' This provides a clear when-to-use scenario and a named alternative. It also notes that the tool makes no API call, implying it is for quick checks rather than live operations.

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 of behavioral disclosure. It details the live join behavior, truncation contract, refusal with candidate list when confidence is low, key normalization, null key handling, join types, and column suffixing. This is exceptionally transparent for a data 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 a single dense paragraph that front-loads the core purpose, then logically covers optional behavior, key handling, and an explicit usage recommendation. Every sentence adds valuable information without 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?

The description is highly complete given the tool's complexity, covering core behavior, edge cases, and output details. However, it does not explain the 'folder_path' parameter, which is part of the schema. While not critical to the main join functionality, this leaves a minor gap in the overall contextual picture.

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 description coverage, so the description must compensate. It explains the semantics of left_on/right_on, join_type, limit, and the data.keys output field. It even covers edge cases like colliding column names and normalized matching, adding rich meaning beyond the raw parameter names.

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 'Joins two sheets LIVE on key columns and returns the merged rows,' naming a specific verb and resource. It also distinguishes itself from sibling tools by explicitly recommending this tool over stitching filter_sheet results together.

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

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

The description includes explicit guidance on when to use this tool versus alternatives: 'Use this instead of stitching filter_sheet results together yourself.' It also explains the optional behavior of omitting key parameters and the server's decision-making process, giving the agent clear context for invocation.

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 behavioral disclosure burden, and it does so thoroughly: it states that only the key column and matched row are read, never whole sheets; it explains the confidence signals (high/ambiguous/conflict) and their consequences; and it mandates citing provenance. This goes far beyond what the schema alone could convey.

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 long but well-structured and front-loaded with the core behavior, then branches into invocation modes, confidence semantics, and a hard safety rule. The line breaks and indented sections make it scannable, and every paragraph adds necessary information rather than padding.

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 complexity and the lack of annotations, the description is exceptionally complete: it covers both call styles, scope, confidence interpretation, fallback suggestions, and provenance requirements. An output schema exists for return-value structure, so not restating the full return object is acceptable. The omitted folder_path parameter is minor and does not undermine the overall 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?

The schema has 0% description coverage and bare properties, so the description must compensate. It adds real meaning to query, key_column, key_value, return_column, and scope with examples and semantic roles. The only gap is folder_path, which is never mentioned, and the description does not explicitly state the mutual exclusivity of query versus explicit key 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 opens with 'ONE-CALL semantic lookup: finds a single cell value anywhere in the workspace and returns it WITH PROVENANCE...' — a specific verb and resource that clearly distinguishes this from generic query or get_cell tools. The two invocation modes (natural language vs explicit keyed) leave no ambiguity about what the 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 gives explicit guidance on when to choose the natural-language mode versus the explicit keyed mode, including the trigger 'Use this when the query form reports it could not parse, or for values too rare to be sampled.' It also explains how scope narrows the search. However, it does not explicitly compare against sibling tools or state when NOT to use lookup, so it falls just short of full alternative-based guidance.

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

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

With no annotations, the description carries the full burden and goes beyond a basic statement of function. It discloses the RAG mechanism, that data is fetched live from OneDrive, and importantly warns about non-deterministic behavior when routing_ambiguous is true, where the choice is 'effectively arbitrary.' This level of behavioral disclosure is exceptional.

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 the ideal but every sentence earns its place: purpose, mechanism, usage, parameters, ambiguity warning, routing tip, and alternative tool. It is front-loaded with the primary purpose and structured clearly, though it could be tightened slightly without losing 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 complex tool with no annotations and a rich output schema, the description covers the essential decision factors: when to use it, how it works, how to interpret routing ambiguity, and how to confirm live data. It also points to the output schema via metadata.fetched_at, making it sufficiently complete for an agent to invoke correctly.

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, so the description must compensate. It explains n_results (count, default 5) and min_score (threshold for weak matches), and the question parameter is self-evident. However, folder_path is not described at all, leaving its role to inference from its name, which is a small gap.

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 this is a natural-language query tool with automatic RAG routing, describes the full pipeline (embed, retrieve, rerank, fetch live), and explicitly distinguishes it from filter_sheet for known file/sheet combinations. This leaves no ambiguity about what the tool does and when it is the right choice.

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

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

The description explicitly tells the agent to use this tool for exploratory questions when the specific file or sheet is unknown, and names filter_sheet as the alternative for known cases. It also provides actionable guidance for ambiguous routing ('confirm with inspect_file or ask the user') and tips for improving routing accuracy.

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 transparency burden. It discloses that the operation is SLOW and makes many API calls, and explains that it rebuilds the index and embeddings. It doesn't detail side effects (e.g., does it overwrite the existing index?), but it provides strong behavioral context and performance warnings.

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?

Every sentence earns its place: first states the action, then the performance warning, then precise call conditions, then explicit what-not-to-dos, and finally the alternative tool. It's front-loaded and highly scannable.

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?

Despite its short length, the description covers all decision-relevant context: when to use, when not to use, performance implications, and a link to a faster alternative. Since an output schema exists, the description doesn't need to detail return values. This fully equips an agent to decide correctly.

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 shows one optional folder_path parameter with no description, and the description never mentions this parameter. Since schema_description_coverage is 0%, the description should clarify whether folder_path is the OneDrive root or a subfolder, but it does not. The only implicit hint is 'the OneDrive folder', leaving the parameter's behavior ambiguous.

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

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

The description opens with a specific verb and object ('Rescans the OneDrive folder') and explains the purpose (rebuilds structure index and embeddings). It clearly distinguishes itself from get_workspace_graph by positioning itself as an occasional maintenance operation.

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

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

The description gives explicit, highly actionable usage criteria: only call when new .xlsx files are added or sheet/column names change, and do not call at session start or before every query. It also points to get_workspace_graph as the instant-access alternative.

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