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

With no annotations, the description carries behavioral disclosure. It explicitly mentions that validate_document_input is called internally before writing, that dry_run previews without writing, and it summarizes return fields. It does not detail in-place editing behavior or duplicate-name handling, but the core side effects are disclosed.

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 Args and an example, and no significant filler. It is somewhat long due to the number of parameters, but every section supports correct 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?

Given the tool's complexity—14 parameters, validation behavior, and write side effects—the description is complete. It includes parameter meanings, defaults, dry_run semantics, return information, and a thorough example, so an agent has enough context to call it 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?

Although the schema itself has 0% description coverage, the Args section explains all 14 parameters, including defaults, purpose, and expected formats. The example further clarifies actor_contact structure and typical usage, fully compensating for the schema's lack of descriptions.

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

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

The description clearly states the action: 'Add a new COBie Document row to link a file/reference to a COBie entity.' It identifies the specific resource and purpose, distinguishing it from read-only or update-oriented sibling tools.

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

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

The intended use is implied by 'Add a new COBie Document row,' and the description mentions internal validation and dry_run, but it does not explicitly contrast this tool with alternatives like update_cobie or validate_document_input, nor state when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It discloses the confirmation requirement and failure conditions, but does not explicitly state that this permanently mutates the graph or describe other side effects such as overwriting existing data.

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 concise sentences with the purpose front-loaded. It contains no redundant information or unnecessary detail.

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 having an output schema, the description gives minimal context for constructing structured_update_json, understanding diff semantics, or formatting actor_contact. For a complex mutation tool, this is insufficient for an agent to invoke it correctly without additional external knowledge.

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?

Only dry_run and confirm_token are explained in the description. The parameters diff, project_id, actor_contact, and structured_update_json are not described, and the schema has 0% description coverage, leaving their meaning and purpose unclear.

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

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

States a specific action 'Apply COBie updates to the canonical project graph' and clarifies it is not Excel. This clearly distinguishes it from sibling tools like preview_update and import_cobie_to_graph.

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 usage conditions: requires confirm_token='CONFIRM_APPLY' unless dry_run=True, and rejects when graph sync status is missing, stale, or error. However, it does not explicitly mention alternative tools or when to prefer them over this one.

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 burden of explaining side effects, and it does explain in-place editing, output_path behavior, and create_backup. However, it does not describe the dry_run or diff parameters, which control whether changes are actually applied or previewed, so transparency is not complete.

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?

Although lengthy, the description is well structured with headers, bolded field names, JSON examples, and a common-mistakes list. Every section serves a purpose, and the most critical behavioral warnings are 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?

The description includes complete examples, required actor_contact structure, payload field rules, and header requirements, which is excellent for a tool with nested objects and no schema descriptions. It would be more complete if it addressed dry_run, diff, and key_mode, which are present in the schema but unexplained.

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 covers most important parameters in prose, including excel_path, payload fields, actor_contact, as_of_date, output_path, and create_backup. It omits documentation for dry_run, diff, and key_mode, and since the schema itself has no per-parameter descriptions, those omissions leave gaps in parameter understanding.

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 captures equipment installation data in a COBie workbook during the construction phase, using a specific verb and resource. It distinguishes itself from sibling tools by focusing on installation records rather than lookup, graph, or document management operations.

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

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

The description provides extensive usage guidance: it tells the agent to call get_update_workflow or get_actor_contact_schema first, explains the construction-phase workflow, gives minimal and alternative payload examples, and lists common mistakes. It also clarifies what not to ask for (type, floor, space), making the intended use unambiguous.

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

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

No annotations are provided, so the description carries the full burden. It states a read-only operation ('compute hash') with no side effects or dependencies mentioned. While it does not explicitly say it does not modify the workbook, the nature of hashing implies non-destructive behavior, which is sufficient.

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

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

The description is a single, concise sentence that directly conveys the action and purpose. No redundant words or extraneous details, 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?

The tool is simple with one parameter and no output schema. The description fully covers what the tool does and why it is used, without needing to explain return values or side effects. It is complete for the agent's decision-making.

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

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

The only parameter, 'excel_path', is self-explanatory given the tool name and description (path to a COBie workbook). The schema lacks a formal description, but the tool description provides enough context to understand the parameter's role. No additional ambiguities exist.

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

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

The description clearly states the action ('Compute'), the object ('canonical source hash'), and the context ('for a COBie workbook' and 'for graph sync checks'). It distinguishes this utility from other COBie and graph tools by specifying its hashing purpose.

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

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

The phrase 'for graph sync checks' gives a clear usage context, implying this tool is used when verifying consistency between COBie data and graph state. It does not explicitly mention when not to use it or name alternatives, but the purpose is specific enough for an agent to select 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?

There are no annotations, and the description does not disclose side effects such as writing a file to output_path, whether the graph is modified, or whether existing files are overwritten. The full burden falls on the description, which only states the high-level export action.

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, clear sentence with no redundant wording. It is front-loaded with the action and object, making it 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?

Despite an output schema being present, the description alone is too sparse for a tool with three parameters and no annotations. It omits parameter semantics, output behavior, and any details about the optional validate flag, leaving significant gaps for an agent.

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

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

The input schema provides only types and titles, with 0% description coverage. The description does not explain project_id, output_path, or the optional validate parameter, so an agent cannot infer their meanings or expected formats.

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 ('Export'), a specific resource ('derived COBie Excel snapshot'), and the source ('canonical project graph'). This distinguishes it from sibling tools like import_cobie_to_graph and validate_cobie.

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 use this tool versus alternatives such as import_cobie_to_graph, load_cobie_summary, or get_cobie_headers. There is no mention of prerequisites, scenarios, or conditions that would help an agent choose 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?

The description states the return structure (dictionary with sheet names, highlights, row counts) and implies a read-only extraction, but does not disclose side effects, error behavior, or how highlights are determined. With no annotations, more explicit behavioral detail would be beneficial.

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 succinct, includes the essential purpose and parameter explanations, and contains no redundant or extraneous 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?

The description gives the basic purpose, parameters, and return structure, which is sufficient for a simple tool. However, the vague 'highlights' concept and lack of examples or output format details may leave an agent uncertain about what to expect from the result.

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 described: excel_path as the file path and limit_rows as the maximum rows to preview per sheet. This provides clear meaning beyond the bare schema names and types.

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 ('Extract highlights') and resource ('Excel attachment'), and explicitly distinguishes from COBie workbooks, which helps differentiate from sibling tools. However, the term 'highlights' is vague and not further explained.

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 only a negative scope ('not a COBie workbook') and no explicit guidance on when to choose this tool over alternatives like extract_from_submittal or extract_from_text. An agent would need to infer usage context.

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 fully carries the behavioral burden. It explicitly describes the return format (consistent structured output with confidence and provenance), failure handling (actionable error messages, best-effort text with warnings for partial failures), and output minimization (text_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 concise (four sentences), front-loads the main purpose, and provides additional behavioral details without redundancy. It is well-structured 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 simple parameter set (two basic types) and the presence of an output schema, the description covers the core behavior, error modes, and output minimization. No critical information appears missing for correct invocation.

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

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

The schema has no parameter descriptions, and the description does not explain the 'mode' parameter or 'pdf_path' beyond the general purpose. The enum values (text, fields, both) are self-explanatory but not explicitly linked to output behavior, leaving some ambiguity for agents.

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 ('extract') and resource ('PDF submittal'), and lists the extracted contents (text, structured fields, tables), which clearly distinguishes it from sibling tools like extract_from_text and extract_from_excel_attachment.

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

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

The description clearly implies when to use the tool (for PDF submittals) and describes behavior on failure and partial failure, but it does not explicitly mention alternatives or state when not to use it. The sibling tool names and the explicit 'PDF' make the usage clear enough, though not fully explicit.

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 explains the return dictionary but does not mention side effects, file access behavior, or error handling. Since no annotations are present, the description carries the burden, and it only partially addresses this.

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, well-structured, and contains no unnecessary wording. The Args and Returns sections make the tool's behavior easy to grasp.

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 main purpose, parameters, and return fields, which is sufficient for a simple extraction tool. It lacks explicit edge-case or error behavior, but the core usage is clear.

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 briefly described in the Args section, and the mode parameter is clarified as currently only supporting 'content'. This adds useful meaning beyond the bare schema, though path details such as supported file locations are not specified.

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 extracts content from a .txt file and lists the returned information. It is distinct from sibling extract tools by explicitly targeting text files.

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 intended use is implied by the .txt file scope, but the description does not explicitly mention when to choose this tool over sibling tools like extract_from_submittal or extract_from_excel_attachment. No exclusions or alternative 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?

No annotations provided, so description carries full burden. It indicates a read-only operation ('Return'), and does not imply any side effects. It does not explicitly state it is non-mutating, but that is 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?

Two sentences, clear and to the point, no extraneous info.

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

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

Provides sufficient context on when to call and alternative tool, but does not describe output, which is acceptable since the output is the schema itself.

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?

No parameters exist, so schema coverage is complete. The description does not need to add parameter details, and the mention of aliases refers to output content, not 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?

Clearly states it returns the expected structure for actor_contact, including accepted aliases, which distinguishes it from other schema tools for different entities.

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

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

Explicitly instructs to call before capture_installation or update_cobie, and points to get_update_workflow for full checklist, providing clear when-to-use guidance.

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

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

The description mentions 'row 1 only' which provides some behavioral detail, but it does not disclose error handling, return format, or any side effects. Since there are no annotations to supplement, the description carries the burden and is somewhat sparse.

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 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?

For a simple read-only getter, the description provides enough context about what it returns (headers per sheet, row 1 only). The lack of an output schema is mitigated by the simplicity of the operation, though explicit return structure details could enhance 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 only parameter, excel_path, is self-explanatory and the schema covers 100% of parameters. The description does not add additional meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns workbook headers for each sheet, specifically row 1 only, which is a specific verb and resource. It distinguishes itself from sibling tools like list_sheet_rows or get_cobie_hierarchy by focusing solely on headers.

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. While the function is clear, there is no guidance on when choosing this over e.g., list_sheet_rows or get_cobie_hierarchy would be appropriate. The context is implied but not 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?

The description explicitly states 'Read-only', making the non-mutating behavior clear. However, it does not disclose return structure, error behavior, pagination, or aggregation details beyond the word 'aggregated'.

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 with no redundant prose. The 'via domain HierarchyService' detail adds little value but does not significantly hurt 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?

The description is too sparse for the tool's complexity: parameter semantics are absent, output behavior is not described, and no usage context is given despite the large set of sibling tools.

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

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

Schema description coverage is 0% and the description does not explain any of the six parameters. While names like project_id and floor_name are somewhat self-explanatory, q, excel_path, and import_version_id remain ambiguous and are not addressed.

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 identifies the resource as an aggregated COBie hierarchy of floors and notes it is read-only, but 'aggregated' is vague and it does not clearly distinguish this from sibling tools like graph_list_floors_tool or list_floors.

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 use this tool versus the many sibling floor/hierarchy tools, nor are any conditions, prerequisites, or alternatives mentioned.

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 states the tool returns structure and validation rules but does not mention any side effects, prerequisites, or whether the operation is read-only. Since the name implies a read-only getter, the description adds little beyond the name. It also doesn't disclose any potential cost or latency, leaving the agent without explicit assurance of safety.

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 purpose stated first and usage guidance second. It is concise, front-loaded, and every sentence adds value—the first defines what it does, the second explains when to call it. There is no fluff or repetition of the tool name, making it efficient for an agent to parse.

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 has an output schema and zero parameters, the description provides essential usage context (call before adding documents) and explains the benefit (prevents validation errors). It doesn't cover edge cases like whether the schema is static or dynamic, or if there are any prerequisites like project context, but for a simple getter with an output schema, the coverage is adequate. A minor gap is the lack of explicit mention that it's a read-only operation.

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

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

The tool has zero parameters, and the schema coverage is 100%, so the baseline is 4 per guidelines. The description adds context about what the return contains (validation rules, examples, entity references), which helps the agent understand the value of the response even though there are no parameters to clarify. This meets the baseline without needing to compensate for 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 returns the expected structure for a COBie Document, including validation rules and examples. It uses a specific verb 'Return' and names the resource 'COBie Document', making the purpose unambiguous. It doesn't explicitly differentiate from siblings like get_cobie_headers or validate_document_input, but the purpose is clear enough for an agent to select it when needing schema information.

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

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

The description explicitly says 'Call this before adding documents' and explains it helps understand required fields, PickList constraints, and entity references, preventing validation errors. This gives clear when-to-use context. However, it doesn't mention alternatives or explicitly state when not to use it, such as after documents are already added or for other schema needs, leaving some inference required.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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

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

Tool has no description.

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?

Tool has no description.

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 states that it 'Returns' stats, implying a read-only operation, but does not mention side effects, performance implications, or whether it loads the graph into memory. This is adequate but not exhaustive.

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 conveys the essential purpose without superfluous detail. It is well-structured and immediately understandable.

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 explains what the tool returns (node/relationship counts) and the scope (project-scoped). It does not describe the output format, but that is not strictly required since no output schema is provided. The description is sufficient for an agent to decide whether to invoke 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 schema describes project_id as a required string, and the description mentions 'project-scoped', which indirectly references the parameter. Since schema coverage is high (100% of parameters described), the baseline is 3, and the description does not add extra meaning beyond the schema.

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

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

The description clearly states the verb 'Return' and the resource 'project-scoped graph load stats (node/relationship counts)'. It is distinct from sibling tools that list floors, components, or perform searches, so the agent can easily differentiate it.

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

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

The description gives clear context that this is for project-scoped stats, but it does not explicitly mention when to use this tool versus alternatives. No alternatives are named, so guidance is implied rather than explicit.

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

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

The description discloses the return fields but does not mention error behavior, such as what happens when the named skill does not exist. With no annotations, more behavioral detail would be beneficial.

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

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

Two concise sentences deliver the purpose, return fields, and cross-references without unnecessary detail.

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 simple one-parameter interface and clear sibling references, the description is complete enough for an agent to select and call the tool 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 provides no description for the 'name' parameter, but the tool description clarifies that it refers to a skill name discoverable via list_runtime_skills(), adding useful context.

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

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

Clearly states the tool gets a full runtime skill by name and lists the returned fields, distinguishing it from list_runtime_skills and suggest_runtime_skill.

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

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

Explicitly instructs to use list_runtime_skills() for discovery and suggest_runtime_skill() for intent-based selection, providing clear when-to-use guidance.

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

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

With no annotations provided, the description carries the full burden. It makes clear the tool only returns guidance and does not imply any mutation or side effect, which is sufficient for a read-only advisory 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 concise, front-loaded with the core purpose, and every sentence adds useful guidance. 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?

Despite having no input parameters or detailed output schema, the description fully covers what the tool does, why it should be used, and when to call it relative to related operations.

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, so there is no parameter meaning to add beyond the schema. The baseline score of 4 applies.

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

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

The description clearly states the tool returns a recommended workflow for updating COBie workbooks, with a specific verb and resource. It is easily distinguished from sibling tools like update_cobie and capture_installation.

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

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

The description explicitly says to call this first and to use it before capture_installation or update_cobie, giving clear when-to-use guidance and naming the relevant alternatives.

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

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

No annotations exist, so the description carries full burden for disclosing behavior. It only states the return value but does not mention potential side effects, error conditions, or whether it is read-only.

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 without extraneous words. It is well-structured and to the point.

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 lacks context about the vector index, readiness criteria, or how this relates to other vector tools. Given the large sibling set, this minimal information is insufficient for full understanding.

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 project_id is not explained beyond its title. The schema provides no description, and the tool description adds no detail, leaving the agent to guess its format or meaning.

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 returns vector index readiness for a project, using a specific verb and resource. It is distinct from sibling tools, though somewhat terse.

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 the many sibling tools, such as sync_project_embeddings or semantic_search_project. Without alternatives or context, the agent cannot determine appropriate usage.

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 only behavioral trait disclosed is deprecation. There is no mention of read-only nature, side effects, error behavior, or whether it delegates exactly to the canonical tool. Without annotations, this sparse description leaves much about runtime behavior unstated.

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

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

The description is a single sentence, directly states the deprecation and alias relationship, and uses no superfluous words. It is appropriately brief for the narrow purpose of signaling a deprecated alias, though it omits useful context.

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 deprecated alias, the description references another tool but does not provide enough context for an agent to understand what the tool does, what inputs mean, or what outputs to expect. The sibling list includes 'get_vector_status' but the description does not point to it explicitly, leaving the description incomplete for autonomous use.

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 sole parameter 'project_id' has no description in the schema and the tool description adds no meaning. The agent is left to infer that it identifies a project, but receives no format, constraints, or usage hints. Schema coverage is 0% and the description does not compensate.

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 identifies the tool as a deprecated alias for 'get_vector_status', indicating it is a compatibility shim rather than a distinct function. It distinguishes from siblings by name, but does not explain what 'vector status' actually retrieves, leaving the primary purpose ambiguous without external knowledge.

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 labels the tool as deprecated but does not explicitly state that the canonical 'get_vector_status' should be used instead, nor does it provide conditions for when this alias might still be appropriate. No guidance is given on alternatives or migration paths.

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?

There are no annotations describing side effects, and the description does not explicitly state whether this tool is read-only or if it modifies the graph. Since counting is likely non-destructive, that should be stated for clarity.

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 with no redundant information. It is well-structured and immediately readable.

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 adequate for a simple counting operation, but it does not mention the return format or whether it returns a single integer or a structured result. The existence of an output schema is noted, but its contents are not summarized.

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 provides only parameter names with no descriptions. The description gives minimal context that project_id and space_name relate to the project graph and space, but it does not explain their expected formats, meanings, 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 action ('Count'), the object ('components'), and the scope ('located in a space from the canonical project graph'). It is easy for an agent to understand what this tool does.

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

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

The description does not explain when to use this tool instead of closely related siblings such as graph_list_components_by_space or graph_count_spaces_by_floor. It gives no conditions for choosing this tool over alternatives.

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

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

There are no annotations describing side effects, and the description does not mention whether the operation is read-only, destructive, or performs any other behavior. Since the description carries the full burden in the absence of annotations, the lack of any behavioral detail leaves significant ambiguity. The tool name hints at a count operation, but no explicit transparency is provided.

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, consisting of a single sentence with no unnecessary words or filler. It is front-loaded with the most relevant information: the deprecated status and the alias target. This is an appropriate length for a simple alias 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?

The description lacks any mention of return values, output format, or parameter details, and the output schema is not provided in the presented definition. As a deprecated alias, it relies entirely on the referenced tool, but the description does not give sufficient context for an agent to understand the complete behavior. The tool is simple, yet missing return and parameter guidance leaves notable 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 provides no descriptions for the required parameters project_id and space_name, and the tool description does not explain them. Although the parameter names are somewhat self-explanatory, the description does not compensate for the complete absence of schema-level documentation. The agent receives minimal semantic guidance beyond the field 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 states it is a deprecated alias for graph_count_components_by_space, which clearly indicates the intended function by referencing another tool, but it does not explicitly describe what the tool does in its own words. The tool name itself conveys the counting operation, adding some clarity. Overall, the purpose is inferable but not directly stated.

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 marks the tool as deprecated and points to the preferred alternative, graph_count_components_by_space. This provides clear guidance on when to use this tool versus the sibling tool: essentially, the agent should use the non-deprecated version instead. This fully satisfies the usage guidance criterion.

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 indicates a read-only counting operation, but does not explicitly state that no modifications are made or mention any side effects.

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

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

The description is a single, concise sentence with no unnecessary words, clearly stating the action and the object.

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 count operation, the description is sufficient: it specifies the resource, the scope (floor), and the source (graph), making the return value obvious. The presence of an output schema further reduces the need to describe return values.

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?

Neither the schema nor the description provides any explanation for the two parameters (project_id and floor_name), so the agent has no guidance on their expected values or formats.

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 'Count' and identifies the resource 'spaces on a floor' and source 'canonical project graph', clearly distinguishing it from sibling tools like graph_list_spaces_by_floor and graph_count_components_by_space.

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 no explicit guidance on when to use this tool versus alternatives, but the purpose implies it should be used when a count of spaces is needed rather than a list or component count.

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 only that the tool is deprecated. It does not mention any behavioral traits such as read-only status, side effects, or that it behaves identically to the alias target. Minimal transparency is provided.

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 short and concise, but it lacks essential information about the tool's functionality. While it is not verbose, the brevity comes at the expense of clarity and completeness.

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 almost no context. It does not explain what the tool does, when it should be used (other than deprecation), or how it relates to other tools. This is highly incomplete for an agent to correctly 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 schema provides no descriptions for the parameters project_id and floor_name, and the description does not explain them. With zero schema coverage, the description fails to compensate, leaving the semantics completely undefined.

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 does not directly state what the tool does. It only says it is a deprecated alias for graph_count_spaces_by_floor, which implies the functionality but does not explicitly describe it as counting spaces by floor. This is insufficient for a clear purpose.

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 that the tool is deprecated, which clearly signals that it should not be used. It also names the tool it aliases, implying that the non-deprecated alternative is graph_count_spaces_by_floor. This provides clear usage 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 and only a brief description, the tool's behavior is underspecified. It does not mention case sensitivity, substring matching, result ordering, limit semantics, or what happens when no components match.

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 conveys the essential action and target without unnecessary words 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 is too brief for a search tool with no annotation support. It omits matching behavior, result shape, limit behavior, and relationship to sibling search and detail tools, leaving an agent to guess important execution details.

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 includes only types, required flags, and a default for limit; no parameter descriptions are provided. The description mentions 'name' and 'project graph' but does not clarify whether name is a partial match or exact identifier, nor does it explain limit or project_id 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 identifies the action (find) and resource (components by name) within the canonical project graph, distinguishing it from general listing or detail tools. It does not specify whether matching is exact or partial, but the core purpose is understandable.

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 about when to use this tool versus closely related siblings such as semantic_search_project, graph_get_component_details, or graph_find_component_by_name_tool. The description does not help an agent choose among search-like alternatives.

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

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

No annotations are present and the description provides no behavioral information beyond noting it is a deprecated alias. It does not disclose side effects, safety, read-only nature, or any return 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 extremely short and not verbose, but it omits essential content. It is structurally simple and front-loaded with the deprecation notice, yet the minimalism harms usefulness.

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 this is a deprecated alias, the description lacks necessary context about the canonical tool's behavior, output, parameter meanings, and why an agent should or should not use this alias. No output schema or further guidance is provided.

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 project_id, name, or limit, and the description adds no meaning to these parameters. The agent cannot infer what values are expected or how limit affects results.

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 only says 'Deprecated alias for graph_find_component_by_name' and does not state what the tool actually does, such as finding a component by name in a graph. It relies entirely on the referenced canonical tool name for meaning, so the purpose is not directly clarified.

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 indicates deprecation and points to another tool name, but it does not explicitly tell the agent when to use this alias versus the canonical sibling graph_find_component_by_name or other graph lookup tools. No usage conditions or alternatives are described.

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 must fully disclose behavior. It only mentions the source ('canonical project graph') but does not state whether the operation is read-only, what happens if the component is not found, or any prerequisites. This is a minimal disclosure for a graph query 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, well-structured sentence that front-loads the action and resource. It is concise without waste, though it may be too brief given the tool's complexity. Structure is good, but brevity leaves gaps in other dimensions.

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 an output schema existing, the description lacks essential context for an agent: no usage conditions, no differentiation from similar siblings, and no mention of error scenarios. Given the large sibling set and zero annotation coverage, the description is inadequate for correct selection and invocation.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. The description mentions 'component details' and 'type/location' but does not explicitly explain what project_id and component_name mean beyond their self-explanatory names. It fails to add meaningful semantics to the 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 a specific verb ('Get') and resource ('component details and related type/location'), clearly identifying the tool's function. It does not explicitly contrast with siblings, but the focus on 'details' and 'type/location' distinguishes it from location-only tools like graph_get_component_location. It is clear but lacks explicit differentiation.

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

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

No guidance is provided on when to use this tool versus the many siblings, such as graph_get_component_location or graph_get_type_components. The description does not mention alternatives or exclusions, leaving the agent to infer the appropriate context from the 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?

No annotations are present and the description provides no behavioral information such as read-only status, side effects, errors, or output characteristics. The description carries the full burden and fails to disclose any 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 sentence with no unnecessary wording. The deprecation status is front-loaded and the alias target is clearly named.

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 only a deprecation notice and does not explain the actual operation, parameters, output, or appropriate usage context. It is not sufficient for an agent to understand or safely invoke 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?

Schema description coverage is 0% and the description adds no meaning to the parameters. 'project_id' and 'component_name' are only nominally self-explanatory; no format, constraints, or relationship to the operation is provided.

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 identifies the tool as a 'deprecated alias' for graph_get_component_details, but it never states what the underlying operation actually does. An agent must resolve the target tool to understand the purpose.

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 deprecation warning and 'alias' wording imply that the canonical tool should be preferred, but the description does not explicitly say when to use this tool versus alternatives or direct the agent to the replacement.

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 disclose behavioral details such as whether the operation is read-only, what it does if the component is not found, or what the resolved location format will be. The description is too minimal to fully inform an agent about side effects or failure 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 with no unnecessary words. It front-loads the primary action and object, making it easy 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?

The description is adequate for a simple graph lookup but lacks surrounding context such as whether the result includes floor and space names, how it relates to the canonical graph, or when it should be preferred over similar lookup tools. The output schema is indicated as present but not shown, so some return-format ambiguity remains.

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 for project_id or component_name, and the description only indirectly references component location without explaining the expected values or format for these parameters. With zero schema coverage, the description needed to compensate but did not.

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 ('Resolve') and object ('component location'), and indicates the source is the canonical project graph. It does not explicitly contrast with sibling lookup tools, but the phrasing already conveys the main function.

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 no guidance on when to use this tool versus related sibling tools such as lookup_component_location_tool or graph_find_component_by_name_tool. It only describes what the tool does, not the conditions that make it the appropriate choice.

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 only disclosed behavioral trait is deprecation. No information about side effects, permissions, or that it likely behaves identically to the aliased tool is provided. Without annotations, this leaves much to inference.

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 short and to the point, with no unnecessary wording. However, the brevity comes at the cost of essential content, so it is concise but not well-rounded.

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, the description still lacks critical context such as what the alias does, why it is deprecated, and which alternative to use. The output schema is also not explained, leaving the agent underinformed.

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 lists project_id and component_name with no descriptions, and the description adds no semantic meaning to these parameters. The agent receives no help understanding what values are expected or how they are used.

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 only states that it is a deprecated alias for another tool, but it does not directly state what the tool does (e.g., retrieving component location). This is vague and relies on the user knowing the referenced tool.

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

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

It implies the alternative by calling itself a deprecated alias, but it does not explicitly advise when to use it or when to prefer the non-deprecated tool. The guidance is minimal and inferential.

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 only states the listing action and source, but does not mention read-only status, pagination behavior, default limit, error conditions, or the shape of the returned data.

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 front-loads the primary action and resource. It avoids unnecessary verbosity and is appropriately sized for the tool's simple purpose.

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

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

The tool has a moderately simple interface, but the absence of parameter descriptions, usage guidance, and explicit behavioral notes makes it incomplete for an agent to invoke confidently, despite the presence of an output schema.

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 for the three parameters (project_id, system_name, limit). The description does not explain what each parameter means, how they are used, or the effect of limit, leaving the agent to guess or infer from 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 states a clear verb ('List') and a specific resource ('components in a system') from a defined source ('canonical project graph'). It is distinct enough from similar sibling tools like graph_get_type_components and graph_get_component_details, though it does not explicitly differentiate itself.

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 sibling list contains tools like graph_get_type_components and graph_list_components_by_space, but the description does not clarify the appropriate context for selecting 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?

There are no annotations, and the description only mentions deprecation. It does not disclose any behavioral aspects such as side effects, return behavior, or operational characteristics. The agent gets no transparency beyond the deprecation 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?

The description is extremely concise, consisting of a single sentence with no unnecessary filler. It communicates the deprecation clearly, though it lacks substantive content. Structure is simple and appropriate for an alias.

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 context is minimal: the tool is only described as a deprecated alias. It lacks information about what the tool actually does, parameter semantics, and expected output. An agent could only infer behavior from the tool name and sibling context, which is insufficient.

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 provides no information about parameters (project_id, system_name, limit). The schema has no parameter descriptions, so with 0% coverage the description does not compensate. Parameter meanings remain unclear.

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 it is a deprecated alias for graph_get_system_components but does not explicitly describe what the tool does. The name 'graph_get_system_components_tool' is somewhat self-explanatory, but the description alone lacks a clear verb+resource statement.

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 names the canonical tool ('graph_get_system_components') and labels this as a deprecated alias, which clearly tells the agent to use the canonical tool instead. This provides appropriate guidance on when (not) to use 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?

The description gives no details about side effects, ordering, pagination, or output format. While 'list' implies a read-only operation, there is no explicit statement about behavior, and without annotations the description carries the full burden.

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 with no extraneous words. It could be expanded with useful context, but for a simple list operation it is appropriately brief.

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 lacks essential context such as result ordering, filtering behavior, pagination semantics, and relationship to sibling tools. Given the large set of similar graph tools, this minimal description may not be sufficient for an agent to choose and invoke it 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 provides only parameter names and types, with no descriptions. The description does not explain what 'type_name' refers to, how 'project_id' is used, or how 'limit' affects the result list, leaving most parameter semantics undefined.

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

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

The description clearly states the action ('List') and target ('components of a type from the canonical project graph'). It distinguishes itself from sibling tools that list by space or system, though it does not explicitly say 'all' or define the scope of the 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?

No usage guidance is provided. The description does not mention when to prefer this tool over alternatives like graph_get_system_components, graph_list_components_by_space, or graph_get_component_details, leaving the agent to infer the appropriate context.

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 gives no information about side effects, read-only nature, or any behavioral traits. The tool's behavior is completely undisclosed.

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 short, which is concise, but it omits essential information. It is not front-loaded with informative content and does not serve as a useful summary.

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 fails to provide any context about the tool's operation, input requirements, output format, or relationship to sibling tools beyond being a deprecated alias. It is incomplete for safe and correct usage.

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

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

The parameter schema has no descriptions for any fields, and the description does not explain the meaning or purpose of project_id, type_name, or limit. Agents have no guidance on how to populate these parameters.

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

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

The description only states it is a 'Deprecated alias for graph_get_type_components' without explaining what the tool actually does. It implies the purpose matches another tool but does not clarify the functionality or scope, leaving the agent to guess.

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 mentions deprecation, which hints that agents should avoid using this tool, but it does not explicitly state when to use it versus alternatives or provide any context on 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?

The word 'List' implies a read-only operation with no destructive side effects. However, with no annotations present, the description does not explicitly disclose whether the operation is non-mutating, whether it has any side effects, or whether any authentication or rate limits apply.

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 with no redundant or extraneous content. It front-loads the core action and object clearly.

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 too sparse to be fully self-contained. It omits any explanation of the 'q' and 'limit' parameters, does not describe the output or return shape, and provides no context about how this listing relates to the graph model or other component-oriented tools.

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

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

The description only mentions the general notion of a space and does not explain the 'q' parameter or the 'limit' parameter. 'project_id' and 'space_name' are reasonably inferable from their names, but 'q' is ambiguous and the meaning of 'limit' as a maximum result count is not stated.

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

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

The description clearly states the verb 'List' and the resource 'components located in a space from the canonical project graph.' It is specific about the operation and scope, though it does not explicitly distinguish itself from sibling tools such as graph_count_components_by_space or graph_find_component_by_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 provides no guidance on when to use this tool versus alternatives like counting components, finding a component by name, or looking up a component location. There is no mention of intended 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?

The description provides no information about the tool's behavior, side effects, return values, or operational characteristics. There are no annotations to supplement this, so the agent has zero transparency into what happens when the tool is invoked. The alias relationship implies identical behavior to the target, but that is not disclosed in the description.

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 brief sentence with no extraneous words. It efficiently communicates the core fact (deprecated alias) and the target tool. This is perfectly concise, though it sacrifices substance for brevity.

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 deprecated alias, the description fully covers the deprecation status and the replacement. However, it omits any functional context, leaving the agent to infer what the tool actually does from its name or the target tool. This is a moderate gap given that the tool might still be invoked despite deprecation.

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 offers no explanation of the input parameters (q, limit, project_id, space_name). The schema provides types and defaults but no semantic meaning or context. Since the description is just a deprecation note, it adds no value to understanding the parameters' purpose or relationships.

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 only states 'Deprecated alias for graph_list_components_by_space' without describing what the tool does. It does not provide a verb indicating the action or resource, relying instead on the alias target's name for any functional meaning. This is vague and insufficient for an agent to understand the tool's purpose.

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 identifies the tool as a deprecated alias and names the replacement tool (graph_list_components_by_space). This clearly signals to the agent to use the non-deprecated alternative, providing direct usage guidance. However, it does not elaborate on specific conditions or scenarios beyond the deprecation.

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 disclose whether the operation is read-only, any side effects, or performance implications. Since it is a listing operation it is likely safe, but that is not explicitly stated.

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—a single sentence with no filler or redundant information. It efficiently conveys the core action and target resource.

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 large number of sibling tools and the presence of an output schema, the description is far too minimal. It does not explain what the output contains, how it relates to similar tools, or any edge cases. The agent lacks essential context for correct usage.

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

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

The schema includes three parameters (project_id, q, limit), but the description provides no explanation of their meaning or usage. The schema itself has no descriptions or enums, so the agent has no semantic understanding of the 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 a specific verb ('List') and a specific resource ('floors from the canonical project graph'). It distinguishes the source of the data, which helps set it apart from potential sibling tools that may list floors from other sources, 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?

There is no guidance on when to use this tool versus the many sibling tools (e.g., 'list_floors', 'graph_list_floors_tool', 'graph_list_spaces_by_floor'). No conditions or alternatives are mentioned, leaving the agent without direction for tool selection.

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 behavioral aspects are disclosed beyond deprecation. There is no mention of side effects, read-only nature, or any other runtime behavior, and no annotations are provided to fill this 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 a single sentence and is concise, which is appropriate for a deprecated alias. However, it lacks any structured detail about parameters or behavior, making it minimally informative.

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 almost no context: it does not explain what the underlying graph_list_floors tool does, nor does it cover parameters, return values, or proper usage. An agent would need to seek additional information elsewhere.

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 lists three parameters (q, limit, project_id) without any descriptions. The description adds no context about their meaning or usage, leaving the agent completely reliant on 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 identifies the tool as a 'deprecated alias' for graph_list_floors, but does not explicitly state what the tool does. The purpose is only inferable from the referenced tool's name, which suggests listing floors.

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 names graph_list_floors as the non-deprecated target, implying that agents should use that instead. However, it does not explicitly instruct when to use or avoid this tool, leaving the guidance implicit.

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 for disclosing behavioral traits. It does not mention side effects, read-only nature, permissions, error conditions, or any other behavioral details beyond the basic listing action.

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 front-loads the primary action and resource. No unnecessary words 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 is minimal and does not provide enough context for correct usage. With four parameters and no parameter explanations, plus no usage guidance, the description is incomplete even though 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?

The schema has 0% description coverage, and the tool description does not explain any parameters. 'floor_name' is hinted by 'filtered by floor', but 'q', 'limit', and especially the required 'project_id' are completely undefined, leaving the agent without needed meaning.

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

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

The description clearly states the action ('List spaces'), the resource ('from the canonical project graph'), and the optional filter ('by floor'). It distinguishes itself from sibling tools like 'list_spaces' (non-graph) and 'graph_list_floors' (floors, not spaces).

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 'list_spaces' or other graph listing tools. No mention of preferred scenarios or exclusions, leaving the agent to infer from the 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?

With no annotations, the description carries the full burden of disclosing behavior. It only states that the tool is a deprecated alias and gives no information about read-only status, side effects, errors, or rate limits. The name implies listing, but that is not explicit behavioral 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 concise sentence with no unnecessary words. It directly communicates the most important fact about the tool: it is a deprecated alias for another 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?

The description provides the essential alias context and the output schema exists, so return-value details are not required. However, it omits any explanation of parameters or invocation nuances, making it only minimally complete for an agent trying to call 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 schema has four parameters with zero descriptions, and the description does not compensate by explaining any of them. Parameters like 'q' are ambiguous, and there is no guidance on how project_id, floor_name, or limit should be used.

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 tool as a deprecated alias for graph_list_spaces_by_floor, which conveys its intended function by pointing to the canonical tool. It does not restate the full behavior, but the alias relationship is specific and distinguishes it from the non-deprecated sibling.

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 'deprecated alias' phrasing provides practical guidance: agents should prefer graph_list_spaces_by_floor instead of this tool. This is not as explicit as a direct 'use X instead' instruction, but it is sufficient for selecting the correct alternative.

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

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

The description explicitly states 'Read-only', disclosing a key behavioral trait. It also implies the tool computes rather than modifies. However, it does not mention potential side effects (e.g., file access errors, performance on large workbooks) or whether it caches results. Given no annotations are provided, the description carries the full burden, and this is mostly covered but not exhaustive.

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 summary, usage trigger, parameters, and return type. It avoids fluff and each sentence serves a purpose. The use of bullet-like formatting in the Args section enhances readability without extra verbosity.

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 moderate complexity (3 parameters, simple return object), the description is complete enough: it specifies the input workbook, optional filters, the read-only nature, and the output fields. The return structure is covered by the output schema, so it need not be detailed here. It could mention edge cases (e.g., what happens if both sheet and key are omitted), but the 'workbook or a single entity' phrasing implies the whole-workbook case.

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

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

The description adds meaning to each parameter: 'excel_path' is explained as 'Path to the COBie Excel file', and 'sheet' and 'key' are described as optional filters ('Optional sheet name...', 'Optional row key...'). Since schema description coverage is 0%, this explanation compensates well and helps the agent understand how to fill the 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 function: 'Assess handover readiness for the workbook or a single entity'. It uses a specific verb ('assess') and resource ('handover readiness'), and the 'e.g. Component by Name' example adds clarity. It also distinguishes itself from siblings like validate_cobie by focusing on readiness rather than validation.

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

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

The description provides explicit when-to-use guidance: 'Use when the user asks "what's missing", "is this ready", or "correct this record"' and notes 'Read-only' to set expectations. It also specifies the condition 'and an entity (sheet + key) is in context', which helps the agent decide between whole-workbook and single-entity assessment. This is sufficient to route to this tool over siblings.

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

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

With no annotations, the description carries the full burden. It discloses 'idempotent upsert', indicating safe re-runs and update semantics, and 'project-scoped' clarifies scope. However, it does not mention potential overwrites, validation requirements, or side effects on existing graph data.

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 with no redundant fluff. It leads with the verb and includes key qualifiers ('idempotent upsert', 'project-scoped') without over-explaining.

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, return values need not be described. However, the description lacks contextual distinction from several similar import/update tools among the siblings, and does not mention preconditions (e.g., valid COBie file, existing project). It is adequate but not rich.

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% (no parameter descriptions), so the description must compensate. It only implies project_id via 'project-scoped' and excel_path via 'workbook', but leaves import_version_id completely unexplained. This is insufficient for an agent to understand all 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 a specific verb ('Import') and resource ('COBie Excel workbook' into 'project-scoped canonical graph'), which distinguishes it from the many query/export/validate sibling tools. The mention of 'idempotent upsert' also clarifies its write nature.

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 importing a COBie workbook into the graph, but it does not explicitly state when to choose this tool over alternatives like 'apply_update_to_graph' or 'load_cobie_summary'. No direct alternatives or when-not-to-use 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?

No annotations and minimal description; doesn't disclose default limit behavior, q search semantics, required excel_path, or error/filtering behavior. Not contradictory, but very little behavioral detail.

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?

Single concise sentence with no redundant wording; immediately states action and optional filter.

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 an output schema, the description omits parameter semantics and behavioral context (e.g., limit default, q, file requirement), leaving agent to infer how 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?

Only space_name is partially explained by 'filtered by Space'; q, limit, and excel_path are left undefined, and schema has no descriptions, so meaning is mostly inferred from 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?

States a clear action ('List') and resource ('components') with optional Space filtering. Does not explicitly mention Excel/COBie source, but excel_path parameter implies it; still distinguishable from graph-centric sibling tools by Space filter.

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 on when to prefer this tool over siblings like graph_list_components_by_space or lookup_component_location; no mention of prerequisites or alternative selection criteria.

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, and the description does not disclose side effects, permissions, read-only behavior, or return format. The simple 'List all floors' provides minimal behavioral expectations beyond the action itself.

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 with no unnecessary detail or repetition. It is well-structured and easy to read.

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 omits important context such as the meaning of 'canonical mode', how the source is selected, what 'q' and 'limit' do, and the shape of the output. While an output schema exists, it is not detailed enough to fill these 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 description provides no explanation for any of the four parameters (q, limit, excel_path, project_id). With 0% schema description coverage, the tool relies entirely on parameter names, which are insufficient for an agent to use it correctly.

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

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

The description states a clear action ('List all floors') and identifies the data sources ('Floor sheet or project graph'), but the phrase 'when canonical mode is enabled' introduces ambiguity about when each source is used, making it less crisp than it could be.

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 use this tool versus sibling tools like graph_list_floors or graph_list_floors_tool. The conditional 'when canonical mode is enabled' is not explained, so an agent cannot determine the appropriate usage context.

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

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

No annotations provided. The description implies a read-only listing operation and states the returned fields, but does not explicitly declare side-effect-free behavior or permissions, placing some burden on the agent.

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

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

Two concise sentences. Purpose is front-loaded, followed by return details and routing guidance. No wasted words.

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

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

With no parameters and a simple listing purpose, the description is complete. It specifies the key returned fields and points to related tools, covering everything needed for correct invocation.

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

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

Tool has zero parameters, so baseline score of 4 applies. No parameter semantics needed; description covers the output.

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

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

Clearly states it lists available runtime skills for orchestration, specifying the resource (runtime skills) and the action (list). Distinguished from sibling get/suggest skills by focusing on enumeration.

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

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

Explicitly instructs when to use this tool versus get_runtime_skill and suggest_runtime_skill, including an example for routing user intent. No ambiguity about alternatives.

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

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

The description explicitly discloses that the tool is read-only and returns columns and rows with stable rowIndex identity. Since no annotations are present, this carries the behavioral transparency burden and does so reasonably well, though error behavior and edge cases are not covered.

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

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

The description is concise and free of unnecessary detail. Two sentences convey the core action, read-only nature, and return shape 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 provides enough context for a basic invocation: what it lists and what it returns. However, it omits parameter semantics and details about filtering/pagination behavior, leaving some ambiguity for more advanced use.

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 for parameters and the description does not compensate. excel_path and sheet_name are somewhat self-explanatory, but q is ambiguous and limit lacks contextual explanation, so parameter semantics are effectively undocumented.

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 and resource: 'List rows from any COBie worksheet.' It also mentions the read-only nature and stable identity via rowIndex, which distinguishes it from specialized sibling tools like list_components or list_floors.

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?

There is no explicit guidance on when to use this tool versus alternatives. The phrase 'any COBie worksheet' implies generic raw row access, but no sibling tools, exclusions, or edge-case usage are mentioned.

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?

There are no annotations, so the description carries full responsibility for disclosing side effects. The verb 'List' implies a read-only operation, but it doesn't explicitly state whether it accesses local files, queries a graph, or has any side effects on the workbook or graph.

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, using a single sentence with no redundant information. It gets straight to the point and is easy to read.

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 lacks essential context such as the required parameter (excel_path), how q and limit work, and the expected output structure. Although an output schema is indicated, the description still leaves too many behavioral and input details unspecified.

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%, and the description only hints at 'Floor' and 'workbook or project graph'. Parameters like q, limit, and the required excel_path are not explained, and the relationship between excel_path and project_id remains unclear.

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

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

The description clearly states the action ('List spaces') and the object ('spaces'), with an optional filter by Floor. It distinguishes itself from graph-only siblings by mentioning both 'workbook or project graph', though it doesn't name alternative tools.

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

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

The description provides no guidance on when to use this tool versus the more specific sibling tools like graph_list_spaces_by_floor. It also doesn't clarify whether to use the workbook or the project graph, or when each input is appropriate.

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

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

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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

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

Tool has no description.

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?

Tool has no description.

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?

There are no annotations and the description does not disclose whether the operation is read-only, whether it requires any special permissions, or what side effects might occur. 'Resolve' implies a non-mutating lookup, but this is not explicit, and no error or edge-case behavior is mentioned.

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, using one clear sentence. It avoids unnecessary detail, though it could benefit from a brief note about the optional parameters without becoming 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 description is too sparse to be complete. It does not explain the return format, how the optional parameters affect the lookup, what happens when a component is not found, or how this tool differs from the many similarly named siblings. The presence of an output schema is not enough to compensate for the lack of contextual guidance.

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?

None of the four parameters are described in the schema or the description. While component_name is inferable from the tool name, excel_path, project_id, and import_version_id have no explanation of their roles, relationships, or when they are needed. The schema provides only titles and types, so users cannot confidently determine correct values.

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: to resolve a component's assigned Space and Floor. The verb 'Resolve' and the object 'Component's assigned Space and Floor' are specific, and the phrase 'without LLM routing' helps distinguish it from semantic or LLM-based lookup tools.

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

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

The description gives minimal guidance on when to use this tool versus the many sibling tools like graph_get_component_location, lookup_component_location_tool, or graph_find_component_by_name. It only says 'without LLM routing,' which is not enough to disambiguate among the numerous location/component lookup 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, and the description only mentions deprecation and alias status, without describing any specific behavior, side effects, or return value. This leaves the agent uninformed about the tool's actual 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 a single short sentence that directly conveys the deprecation and alias relationship, with no unnecessary words.

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

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

The description provides the essential fact that this is a deprecated alias, but it omits any information about parameters, output, or behavior, making it insufficient for a new agent to understand the tool's full context. However, since it directs to the canonical tool, it partially compensates.

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 does not mention any of the four parameters (component_name, project_id, excel_path, import_version_id), so the agent has no semantic guidance beyond the schema's default values.

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 identifies the tool as a deprecated alias for lookup_component_location, which gives a specific purpose (to redirect to the canonical tool) but does not state the underlying functionality. This is clear enough to distinguish it from siblings but lacks a direct verb.

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 it is deprecated and an alias for lookup_component_location, telling the agent to use that tool instead. This is strong guidance on when not to use 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?

The description mentions the file is not modified, which is a useful side-effect guarantee. However, with no annotations provided, it does not disclose what the tool actually does beyond the vague 'shadow canonical normalization' or whether any other state is changed.

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 short but not clear; the phrase 'shadow canonical normalization' is overly terse and jargon-heavy. It lacks a functional explanation and front-loads ambiguous terminology instead of actionable details.

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

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

The tool description does not specify the output, return format, or behavioral guarantees beyond not modifying the file. Given the large set of sibling tools and the single parameter, the description is insufficient for an agent to know what to expect or how to interpret results.

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 only parameter, excel_path, has no schema description and the tool description does not explain its format, expected file type, or constraints. This leaves the agent with no meaningful semantic information about the input.

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 ('normalize') and resource ('COBie workbook'), and notes it does not modify the file, which helps distinguish it from update-oriented tools. However, 'Shadow canonical normalization' is jargon and does not clearly explain what normalization means or what the tool returns.

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 the many sibling tools, such as validate_cobie, update_cobie, or load_cobie_summary. It does not mention alternatives or conditions that would make this tool the preferred choice.

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 explaining behavior. It states the copy/move behavior based on the copy flag and notes the default is to copy. It does not mention potential side effects like overwriting existing files, handling missing source files, or whether it creates directories. Since it covers the core operation but omits edge-case behavior, a score of 3 is appropriate.

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

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

The description is well-structured with clear sections: purpose, target path, usage note, Args, Returns, and Example. Each sentence adds necessary information without redundancy. The example is concise and directly illustrates the expected output. It is appropriately sized for the tool's complexity, with no filler 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?

The description fully explains the tool's role in the larger workflow (organizing files before adding metadata), the exact target path format, and the return values used by add_document. It provides an example that ties the inputs and outputs together. It does not address error conditions or overwrite behavior, but for a file organization utility in this context, the information is sufficiently complete for an agent to use it 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 six parameters with no descriptions, but the Args section explicitly explains each one, including the meaning of sheet_name and row_name in the target path, and the function of copy and filename_override. This adds significant semantic value beyond parameter names, providing clear mapping to the path template. The coverage is complete and explanatory, warranting a 4.

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: 'Copy/move a file to the standard COBie document location.' It specifies the target path template and clarifies its role in the workflow by returning values for add_document. This distinguishes it from sibling tools like add_document or extract_from_submittal, making its purpose unambiguous.

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

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

The description provides explicit guidance on when to use it: 'Use this to physically organize documents before adding metadata to Excel.' It also explains the return values are meant to be passed to add_document, implying the alternative of using add_document directly if organization is unnecessary. It stops short of an explicit when-not-to-use comparison with other tools, but the context is sufficiently clear.

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

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

The description openly discloses that this is a non-committing dry-run, returns a diff, and explicitly warns that 'No confirm_token on server; client enforces confirm_token'. With no annotations provided, the description carries the full transparency burden and meets it well.

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

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

The description is well-structured with clear sections for preview gate, Args, Returns, and Example. The formatting is scannable and thorough without being redundant; every sentence serves a purpose.

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

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

Given the complexity of a dry-run preview with nested objects and a gate mechanism, the description provides a full example, return structure hints, and usage context. It covers all necessary aspects for an agent to invoke the tool correctly and know what to expect.

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 for the 5 parameters, and the description adds meaningful semantics for each one (e.g., 'Excel file path', 'Same shape as structured_update_json', 'Updater identity'). It even clarifies the nested draft_json structure, fully compensating 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 states a specific verb ('Preview') and resource ('COBie updates') with explicit 'dry-run' and 'return diff'. It distinguishes itself from the sibling update_cobie by framing it as a preview before apply, making the tool's purpose unmistakable.

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 instructs 'Use this before apply' and says to call update_cobie with dry_run=False only after user confirmation. This provides crystal-clear when-to-use and when-not-to-use guidance relative to the sibling update_cobie 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?

No annotations are provided, but the verb 'Search' strongly implies a non-mutating, read-only operation. The description does not explicitly address side effects (e.g., rate limits, caching), but the absence of any mutation language and the presence of a plain return structure make the behavior clear enough.

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: a purpose line, an alternative-guidance line, a compact parameter list, a return type summary, and an example. No redundant or vague wording.

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

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

The return structure is explicitly shown (items with id, label, etc.), an example is provided, and the alternative tools are named. Given the simple parameters and the output schema referenced, the description is complete for an agent to invoke this tool 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?

All four parameters are described in the description with their roles (entity_type, excel_path, query, limit) and allowed values for entity_type. Even though the schema lacks enums, the description covers the full semantics, making the tool self-explanatory.

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 ('Search') on a specific resource ('COBie entities') and enumerates the allowed types, distinguishing it from sibling tools that operate on individual entity types or graph structures.

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 names alternatives for filtered lists (list_floors, list_spaces, list_components) with conditions, telling when NOT to use this tool. Does not fully state when to use it (e.g., 'for cross-type searches'), but the intent is inferable from the listed types and optional query.

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