Ross ERP Data Dictionary

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 clearly states 'Metadata only — no source body,' setting expectations that no code is returned. It also explains the two match labels (declared vs titleId), which is useful behavioral context about the output semantics. This is strong but not exhaustive; it doesn't mention error behaviors or pagination, though these are less critical for a simple metadata lookup.

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—two meaningful sentences plus a clarifying phrase. It front-loads the main purpose, then adds essential details about output labels and relationship to a sibling tool. Every sentence contributes value; no filler or repetition.

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

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

For a tool with a single parameter and no output schema, this description is remarkably complete. It explains what the tool does, what the output looks like (programs with match labels), what the labels mean, the metadata-only limitation, and how it fits with lookup_facility. Given the tool's simplicity, there are no significant 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?

There is one parameter (code), and the schema already provides 100% coverage with a description and example. The tool description refers to 'a UI facility' and uses 'facility code' implicitly, but it adds no additional meaning beyond what the schema already gives. Per the baseline rule, a score of 3 is appropriate when schema coverage is high and the description doesn't enhance 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 opens with a specific verb+resource: 'Cross-link a UI facility to the program(s) that implement it' and clarifies the core question: 'what code runs this screen?'. It also distinguishes itself from sibling lookup_facility by explicitly stating that this tool gives programs while lookup_facility gives tables and call graph, so the purpose is 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 clearly positions the tool relative to lookup_facility: 'Complements lookup_facility (which gives the facility's tables and call graph).' This tells the agent when to use this tool vs that sibling. However, it does not explicitly compare to other siblings like program_facilities or table_programs, so the guidance is good but not exhaustive.

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 transparently describes the output as an overview with totals and breakdowns, making it clear this is a read-only, non-mutating operation. It does not mention potential limitations like performance or access restrictions, but for a simple stats tool, the information provided is adequate.

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

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

The description is two sentences long, front-loaded with the core purpose, and every phrase adds value. It includes concrete examples (ACCOUNTS_PAYABLE, FIN/MAN, REPORT/MAINTENANCE) without unnecessary padding, making it efficient and well-structured.

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

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

Given the tool has no parameters, no output schema, and no annotations, the description is complete. It explains what the overview contains, how it's grouped, and provides usage guidance. Nothing critical is missing for an agent to understand and invoke 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 input schema has zero parameters and 100% coverage, so the baseline is 4. The description adds meaningful context about what the tool returns and how it groups facilities (by system, database, class), which is more than just restating 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 what the tool does: it provides an overview of the Ross ERP 8.0 application layer with total facility counts and breakdowns by system, database, and class. This specific, detailed description distinguishes it from sibling tools like list_facilities or search_facilities, which focus on listing or searching rather than aggregate statistics.

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

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

The description explicitly says 'Use this first to orient before browsing facilities,' providing a clear when-to-use guideline. It does not explicitly name alternative tools or specify when not to use it, but the directive to use it first is sufficient guidance for a parameterless overview tool.

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

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

With no annotations, the description carries the full burden. It discloses the matching behavior ('exact name'), scope ('whole schema'), and the return contents (description, valid values, notes, tables, foreign-key roles). However, it doesn't mention what happens if the column is not found, or whether matching is case-sensitive, which are minor gaps. Overall, it provides substantial behavioral context beyond a simple query.

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

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

The description is one sentence, front-loaded with the verb 'Look up', and packs all essential information without redundancy. Every element earns its place: action, resource, scope, exactness, and the list of returned details. There is zero waste.

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 one-parameter lookup tool with no output schema, the description thoroughly explains the return values: 'description, valid values, notes, every table that carries it, and any foreign-key roles.' It is complete for typical use cases. It could be more complete by addressing not-found behavior, but given the tool's simplicity and the rich return description, it is nearly complete.

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

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

The schema already documents the single 'name' parameter with an example (100% coverage). The tool description adds the 'exact name' requirement, which clarifies matching semantics and excludes wildcard or partial matches. This adds meaning beyond the schema's bare example, so a 4 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's function: 'Look up a single column by exact name across the whole Ross ERP 8.0 schema.' It specifies the resource (column), the action (look up), the scope (whole schema), and the exactness criterion. This distinguishes it from sibling tools like search_columns (likely fuzzy) and lookup_table (table-level).

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: use this when you need a column by its exact name and want comprehensive information across all tables. It does not explicitly mention alternatives or when-not-to-use, but the 'exact name' wording implies a contrast with fuzzy search siblings. A 5 would require explicit exclusions or alternative tool references.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains what the tool returns (DDL with comments and constraints) but does not state whether the operation is read-only, what permissions are required, or how it handles invalid or nonexistent table names. This is a significant gap for a tool that could be assumed to be safe by default.

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 core action: 'Return the CREATE TABLE (DDL)'. It includes relevant details about comments and constraints without any waste or unnecessary jargon.

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

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

For a simple tool with one parameter and no output schema, the description adequately explains the return value and the specific table type (Ross ERP 8.0). However, it could add context about error behavior or the fact that the table must exist, which are not covered. Overall, it is fairly complete for its complexity.

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

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

The input schema fully documents the single parameter 'name' with description and example, achieving 100% coverage. The description does not add additional semantic context, so the baseline of 3 is appropriate—the schema already carries the parameter information, and the description does not enhance it.

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: returning the CREATE TABLE DDL for a Ross ERP 8.0 table, including column descriptions as comments and primary/foreign key constraints. This specific action distinguishes it from sibling tools like lookup_table or search_columns, which are likely about metadata retrieval rather than DDL generation.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. While the purpose implies usage for obtaining DDL, there is no comparison to sibling tools such as lookup_table or schema_stats, leaving the agent to infer applicability.

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, description carries the burden. It discloses that only direct neighbors are returned, not transitive ones, and that relationship type and direction are included. This is meaningful behavioral context beyond a simple 'list' but does not cover potential edge cases or performance implications.

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 sentence, front-loaded with the action, and zero waste. Every clause adds value—scope, object types, and output 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?

Without an output schema, the description appropriately mentions output aspects (relationship type and direction). It does not list all response fields but enough for a basic understanding. A tiny gap is lack of example usage or mention of the default limit, but the schema covers limit.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no extra parameter meaning beyond the schema; it merely echoes that 'name' refers to an object. Limited role in parameter clarity is acceptable given schema completeness.

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?

Clear verb+resource: 'List the knowledge-graph neighbours of an object' with explicit object types (programs, tables, views, procedures) and relationship details. Distinguishes from siblings like lookup_* and path_between by focusing on direct neighbors.

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?

Description conveys clear context: use this to discover directly connected objects. However, it does not explicitly state when not to use it or mention alternative tools (e.g., path_between for paths), missing the 'exclusions' that would earn a 5.

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 behavioral burden. It discloses that results are summaries, supports pagination, and clarifies the withTables filter. It does not explicitly state that it is a read-only operation, but 'browse' strongly implies it, and the return-summaries note adds useful 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 three sentences, front-loaded with the core purpose, and contains no fluff. Every sentence adds value: the first defines scope, the second lists filter capabilities, and the third clarifies the return type and points to a complementary tool.

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

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

Given the tool's complexity, the description covers the core purpose, filtering options, pagination, and return type. It does not specify what the summaries contain or how to handle ordering, and no output schema is provided, but the pointer to lookup_facility partially compensates. It is nearly complete for a listing 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 input schema already provides 100% coverage with clear descriptions for all seven parameters. The tool description names the filter dimensions but adds little beyond what the schema states, so it remains at the baseline for high schema coverage.

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

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

The description clearly states that the tool browses and filters Ross ERP 8.0 UI facilities, specifying the resource and the action. It also differentiates from lookup_facility by noting that this tool returns summaries while lookup_facility provides full detail.

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 for when to use this tool (browsing/filtering summaries) and explicitly recommends lookup_facility for full detail. However, it does not mention when to prefer search_facilities or other sibling tools, so it is not fully explicit about all 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, so the description carries the full burden. It does disclose that the tool returns object summaries and supports pagination via limit/offset, which is useful. However, it omits details about read-only behavior, permissions, default sorting, or any edge cases, providing only basic 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 two concise sentences that are front-loaded with the verb and resource. The first sentence states purpose, the second covers filters/pagination and output behavior. Every clause earns its place with no redundant or filler text.

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

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

For a straightforward list tool with 6 optional parameters and no output schema, the description covers the key aspects: purpose, filter types, pagination, and return summary type. It could more explicitly distinguish from search_all, but the overall context is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a bit of semantic grouping by mentioning filters (type, database, module, name substring) and pagination (limit/offset), but it largely repeats what the schema already documents, so it does not significantly enhance 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?

Description uses specific verb 'browse and filter' and clearly identifies the resource as 'Ross ERP 8.0 objects' with an explicit list of object types. It distinguishes itself from lookup_table by stating that it returns summaries and directs users to lookup_table for full detail, making the 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?

The description gives explicit guidance to 'use lookup_table for full detail,' providing a clear alternative and implying this tool is for browsing/filtering summaries. It explains the filter and pagination capabilities, but it does not explicitly discuss when not to use it relative to other siblings like search_all or find_column, so it stops short of full when/when-not coverage.

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 behavioral burden. It discloses that results are summaries, support pagination via limit/offset, filter by module/type/layer/titled/substring, and that full detail requires lookup_program. It does not cover auth, rate limits, or empty-result behavior, but the core behaviors are well 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?

Three sentences with high information density and no filler. The structure front-loads the purpose and then details filters, pagination, and output behavior. The parenthetical 'application source, metadata only' is slightly awkward but not wasteful.

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 7 optional parameters, no output schema, and no annotations, the description covers the main filter dimensions, pagination, and the summary/full-detail boundary. It could be more explicit about AND-combination semantics and output summary fields, but it is sufficiently complete for an agent to 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining filter semantics (module examples, type letters, layer options, titled meaning) and pagination usage, enriching the schema's parameter descriptions without repeating them verbatim.

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 browses and filters Ross ERP 8.0 programs, identifies the resource (programs) and scope (metadata only), and distinguishes itself by noting that lookup_program provides full detail. This goes beyond the tool name and separates it from related listing/search siblings.

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

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

It explicitly recommends lookup_program when full detail is needed and describes the listing/filtering purpose. It does not explicitly mention when not to use the tool relative to search_programs or other siblings, but the filter-focused language and summary/detail pointer give strong 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, the description carries full burden. It discloses the full scope of the return value, including fields, table clusters (core/reference), and call graph (calls/calledBy) parsed from program source. This goes beyond a generic lookup and gives agents a clear picture of what to expect, though it doesn't mention error conditions or explicitly state read-only 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 long sentence but well-structured with clear lists and parenthetical explanations. It packs substantial detail without wasted words, front-loading the core purpose. The length is justified by the need to enumerate the rich set of return fields, making it efficient despite its length.

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

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

Since there is no output schema, the description must explain return values, and it does so thoroughly, listing every category of detail including name, system, database, class, GEMBASE program, help text, menu paths, table clusters, and call graph. This provides an agent with sufficient information to assess whether the result will meet a query's needs, making the description complete for its complexity.

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

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

Schema description coverage is 100%, so the parameter is already well-documented. The tool description adds only that it's 'by code', which isn't additional detail beyond the schema's 'Facility code, e.g. AP_A_002'. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states a specific verb ('lookup') and resource ('facility by code'), enumerating the detailed fields returned (name, system, database, class, etc.). It distinguishes itself from siblings like list_facilities and search_facilities by emphasizing 'Full detail for one ... facility by code' and listing unique aspects like call graph and table clusters.

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

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

The description conveys that this is for retrieving comprehensive details of a single facility when its exact code is known. It doesn't explicitly name alternatives or exclusions, but the contrast with list/search tools is implicit through the focus on one facility and 'by code'. This is clear context, though not exhaustive about 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 explicitly states 'Metadata only — no source body,' and defines write classification (FIND IN.../LOCK=WRITE, ADD, DELETE) and writeCount. It also explains fallback naming for programs without a TITLE label. This is detailed, though it doesn't explicitly address side effects or error behavior.

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

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

The description is a single long sentence but structured with colons and em-dashes. It front-loads the core purpose ('Full detail for one Ross ERP 8.0 program') and then enumerates contents. While long, every item adds value; no filler or repetition.

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

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

For a tool with no output schema, the description thoroughly enumerates what will be returned: module, type, layer, title, procedures, table references with read/write classification and writeCount, call graph (both directions), menu facilities, and a fallback display name. It also clarifies the absence of source body. This is complete for a metadata lookup.

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 'id' is already fully described in the schema ('Program id or basename, e.g. AP_A_002 or ap_a_check_register'). The description repeats these examples but adds no new semantic information beyond what the schema provides. Therefore baseline 3 applies.

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

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

The description begins with 'Full detail for one Ross ERP 8.0 program' and enumerates specific attributes (module, type, layer, procedures, table refs, call graph, menu facilities). This clearly distinguishes it from sibling lookup tools like lookup_facility and lookup_table.

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 by stating 'Full detail for one program' and giving input forms, but it does not explicitly contrast with sibling tools such as search_programs or program_stats. No 'when to use' 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, yet it does not explicitly state that the operation is read-only, nor does it mention error handling, permissions, or side effects. The name 'lookup_table' implies a read operation, but the description itself only lists return contents and offers no behavioral context beyond that.

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 core purpose ('Full schema for a Ross ERP 8.0 object') and then lists what's included. Every word adds value, and there is no redundancy or extraneous 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 no output schema, the description does an excellent job of enumerating the return contents: columns with type/nullability/keys, valid values, foreign keys in/out, related tables, and usage. It covers all major aspects of a schema lookup. It falls short only by not mentioning error behavior (e.g., object not found), which is a minor gap for a well-scoped lookup tool.

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

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

Schema coverage is 100% with the 'name' parameter clearly described via an example ('GL_ACCOUNTS or ACCOUNT_TYPES'). The description adds no additional parameter semantics, but the schema already fully documents the parameter, so the baseline of 3 is appropriate.

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

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

The description clearly states what the tool returns: 'Full schema for a Ross ERP 8.0 object' with a detailed enumeration of schema components (columns, types, keys, FKs, related tables, usage). It differentiates from siblings like find_column or get_ddl by emphasizing the comprehensive schema scope rather than a specific column search or DDL generation.

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

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

The description implies the tool is for retrieving complete schema details for a named object, but it does not explicitly state when to use this over alternatives such as find_column or list_objects. There are no exclusions or situational guidance, leaving usage to be inferred from the 'full schema' wording.

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 burden of behavioral disclosure. It does disclose the traversal semantics ('through calls / references / accesses') and implies a read-only operation via the verb 'Find'. However, it does not disclose details such as the exact return format, behavior when no path exists, or any limitations like depth or cycle handling. This is partial transparency, warranting a 3.

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, front-loaded sentence that directly states the action and clarifies the relationship types. Every word earns its place, with no filler or repetition.

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

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

The tool has no output schema and no annotations, so the description must explain return values and edge cases. It explains the purpose and traversal edge types but does not specify what the output looks like (e.g., a list of nodes, a distance) or behavior when no path exists. This is a noticeable gap, making the description adequate but not fully complete.

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

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

The input schema already provides descriptions for 'from' and 'to' as 'Start object name' and 'Destination object name' with 100% coverage. The description's phrase 'how A reaches B' reinforces the directional meaning (A=from, B=to) and adds context that the path traverses specific edge types, but it does not add parameter-specific details like case sensitivity or name format. Thus it stays at the baseline of 3.

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: 'Find the shortest path between two objects in the Ross ERP 8.0 knowledge graph.' It specifies the verb (find), the resource (knowledge graph), and the scope (shortest path between two objects). This distinguishes it from sibling tools like graph_neighbors, which likely return direct connections rather than full paths.

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

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

The description provides clear context: it is for finding how one object reaches another through calls, references, or accesses. It does not explicitly mention when not to use it or alternatives, but the phrasing 'how A reaches B' implies a pathfinding scenario, distinguishing it from neighbor-query or search tools. No exclusions are stated, so it earns a 4 rather than 5.

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 transparency burden. It discloses the output context ('one program often serves several facilities') and the nature of results ('each facility carries the same declared / titleId match label'), indicating a read-only query. It does not explicitly state safety or error behavior, but the clear query phrasing and output expectations are sufficient for a lookup tool.

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

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

The description is two sentences, front-loaded with the core purpose and inverse relationship, followed by lookup instructions and output characteristics. Every sentence adds value, and there is no redundancy or fluff.

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

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

For a simple lookup tool with one parameter and no output schema, the description explains the purpose, relationship, valid id formats, and output label match. It is mostly complete, though it could mention response structure or behavior when no matches are found, but these are minor omissions given its simplicity.

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

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

The schema already fully documents the parameter 'id' with examples (AP_I_001 or ap_i_vendors). The description repeats these exactly ('TITLE id (e.g. AP_I_001) or basename (e.g. ap_i_vendors)') without adding additional semantic meaning. Since schema coverage is 100%, the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'which UI facilities... a program backs' and immediately contrasts with the sibling tool 'facility_programs', distinguishing it as the inverse operation. It uses a specific verb and resource, with examples of valid inputs.

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 mentions the reverse relationship to facility_programs, giving context on when to use this tool (when you have a program and want facilities). It also provides lookup by TITLE id or basename, which guides usage. However, it does not explicitly state when not to use it, hence 4 rather than 5.

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

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

With no annotations, the description carries the full burden and does well by noting 'metadata only, no source body' and detailing exactly what counts are provided. It implies read-only behavior but does not explicitly state 'no side effects' or mention auth/rate limits, which are not relevant here but could be more explicit.

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

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

The description is a single dense sentence that front-loads the purpose and enumerates specific metrics. It is somewhat long but every clause adds information; it could be improved with bullet points, but it remains efficient and free of filler.

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

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

For a stats tool with no parameters and no output schema, the description is quite complete: it lists all major metrics, the scope ('every application-source program'), and the intended first-use context. It does not specify the exact output format (e.g., JSON fields), but that is minor given the descriptive enumeration.

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 the baseline score is 4. The description correctly does not attempt to document parameters, and the schema already covers the empty parameter list fully.

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

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

The description clearly states it provides an 'Overview of the Ross ERP 8.0 program catalog' with a specific list of metrics (totals, TITLE id counts, table links, read/write counts, etc.). This distinguishes it from sibling tools like list_programs or lookup_program, which deal with individual programs or listings.

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 final line 'Use this first to orient before browsing programs' gives explicit guidance on when to use the tool. It does not explicitly name alternatives or provide when-not-to-use exclusions, but the context implies it precedes other browsing tools.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does a good job by enumerating what the tool returns, making the output expectations transparent. However, it does not explicitly state that it is a read-only operation or mention any potential performance limitations, which prevents a perfect score.

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

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

The description is a single, well-structured sentence with a colon-led list of contents. It is front-loaded with the main purpose and includes the usage hint, with no wasted words. It is appropriately concise for the amount of information conveyed.

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 zero-parameter tool with no output schema, the description fully covers what the agent needs: the purpose, the exact contents of the result, and the contextual recommendation to use it first. No additional details seem necessary for effective 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 input schema has zero parameters, so there is nothing to document. The description's phrase 'in one call' reinforces that no arguments are needed, which is sufficient. The baseline for zero parameters is 4, and the description adds no unnecessary details.

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

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

The description clearly identifies the action ('Overview ... in one call') and the specific resource (Ross ERP 8.0 schema), listing exactly what is included: object counts, module list, column totals, audit-twin pairs, and top tables/columns/modules. This distinguishes it from sibling tools like facility_stats or program_stats, which focus on specific subsets.

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

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

The description explicitly states when to use it: 'Use this first to orient before drilling in.' This provides clear usage guidance and implies that other sibling tools are for deeper investigation, making it a proper entry point.

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 discloses cross-domain behavior, per-domain limit handling, and type scoping. It does not describe output structure or side effects, but for a read-only search tool this is adequate and goes beyond the schema by explaining the multi-domain granularity.

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

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

Two sentences, front-loaded with the core purpose, followed by usage guidance. Every word earns its place; no filler or redundant information.

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

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

The tool is simple (3 params, 1 required) and the description covers purpose, usage context, and parameter behavior. It lacks output format details, but with no output schema and read-only nature, this is acceptable. It is complete enough for an agent to select and 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?

Schema covers all three parameters with descriptions, so the baseline is 3. The description adds the example phrase and reiterates the 'limit is per domain' and 'type default all' nuances already present in the schema. It does not provide meaningful additional parameter semantics beyond the schema.

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

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

The description clearly states the tool performs a cross-domain search across schema objects, columns, UI facilities, and programs in one call. It uses a specific verb (search), names the resources (objects, columns, facilities, programs), and distinguishes it from per-domain 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?

It explicitly says to use this tool when you don't know which layer a term lives in, with a concrete example. It does not name alternative tools or state when not to use it, but the use case is clear and the per-domain scope option is 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?

No annotations are provided, so the description carries the full burden. It discloses that it searches by name and column descriptions and returns matching objects and columns, which gives some insight into behavior. However, it does not specify whether the search is case-insensitive, if it supports wildcards, whether results are paginated, or any other behavioral traits. This is minimal disclosure for a search 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, front-loaded sentence that covers the core purpose without any redundant phrasing. It is maximally concise and well-structured.

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

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

For a simple search tool with two well-documented parameters, the description is minimally viable. It states what is searched and the return type. However, given the abundance of sibling search tools and the lack of output schema, there are notable gaps in usage guidance and behavioral detail that prevent a higher score.

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

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

The input schema provides 100% parameter coverage with clear descriptions: 'query' has examples and 'limit' has a default and range. The tool description adds no additional parameter information, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: 'Search the Ross ERP 8.0 schema by name (and column descriptions). Returns matching objects and columns.' It has a specific verb and resource. However, it does not explicitly differentiate from siblings like find_column or search_all, relying on the tool name for distinction.

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. It does not mention search_all, find_column, or any specific scenario where search_columns is preferred. This is a significant gap given the number of sibling search 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 present, so the description carries the transparency burden. It discloses that the search can be based on multiple fields, but does not describe return behavior (what a result looks like, whether matches are partial or exact, pagination beyond the limit parameter). This is a noticeable gap for a search tool without an output schema.

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

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

The description is exactly two sentences, with the primary action and scope in the first sentence and a practical usage example in the second. No wasted words; every sentence serves a clear 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 moderate complexity of a search tool and the absence of an output schema, the description provides sufficient context for an agent to understand what to search and why. It does not describe the return format, but the tool's purpose is clear and the example use cases make it actionable.

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

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

Schema coverage is 100% and both parameters have descriptions. The description adds meaningful semantics by specifying that the query can match code, name, help text, program, or tag, which enriches the query parameter meaning beyond the schema's terse example.

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 searches Ross ERP 8.0 UI facilities, specifying the searchable attributes (code, name, help text, program, tag). It also differentiates from siblings like search_programs by focusing on facilities/screens/reports, making the purpose unambiguous.

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

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

It explicitly says 'Use this to find the screen/report for a task' with concrete examples ('check register', 'purchase order receipts'), providing clear when-to-use guidance. It does not mention when not to use it or alternatives, but the use case is specific enough.

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

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

No annotations are provided, so the description carries the burden. It discloses searchable fields and example inputs, which gives some insight, but it doesn't mention result format, pagination, or other behavioral details. This is adequate for a simple search tool but not rich.

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

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

Two sentences, front-loaded with the main purpose and a concrete example. Every word earns its place with no 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 2-param schema and no output schema, the description is fairly complete. It covers the search scope and gives a realistic use case. It could mention the optional limit default but that's in the schema. Overall, sufficient for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about searchable fields, but the schema already provides examples for the query parameter. No significant additional meaning beyond the schema.

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

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

Clearly states it searches Ross ERP 8.0 programs by multiple fields (basename, TITLE program-id, title, module, type) with a specific example. The verb 'search' and resource 'programs' are explicit, and the example distinguishes it from sibling search tools.

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

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

Provides a specific use case: 'Use this to find the program behind a task, e.g. check register or ap_a.' This gives clear context for when to use the tool, though it doesn't explicitly mention alternatives or when not to use it.

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

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

Since no annotations are provided, the description carries the full burden. It discloses the output structure (core vs. reference, access counts) and clarifies what 'touch' means. It does not explicitly state read-only behavior, but the nature of a reverse lookup and the wording 'accesses' imply a safe query 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 two sentences with no wasted words. It efficiently packs the reverse lookup purpose, the core/reference split, and the access count detail in a structured dash clause. The final question reinforces the tool's intent without redundancy.

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

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

For a single-parameter lookup tool with no output schema, the description is adequately complete. It tells the user exactly what the tool returns (facilities split by core/reference with counts) and answers the primary use case. No significant behavioral detail is missing.

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

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

The schema already provides full coverage for the single 'table' parameter with an example (GL_ACCOUNTS). The description only adds the Ross ERP domain context and does not introduce new parameter-level semantics beyond the schema, matching the baseline of 3.

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 reverse lookup from a given Ross ERP 8.0 table to UI facilities, and further specifies the split into core and reference with access counts. The 'Reverse lookup' phrase and the question 'what screens read or write this table?' effectively distinguish it from forward lookup tools like lookup_table and table_programs.

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

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

The description implies usage: when you have a table and want to know which facilities (screens/reports/programs) use it, with a clear breakdown. It does not explicitly name alternatives, but the 'reverse lookup' framing and the answerable question provide clear context for when to invoke this tool.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It states that the lookup is validated against the Data Dictionary and that it is 'Metadata only — no source body', which clarifies important behaviors. It does not explicitly mention being read-only, but 'reverse lookup' and 'metadata only' strongly imply a safe read 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 two sentences, front-loaded with the core purpose and then providing differentiation and limitations. Every phrase adds value: the reverse lookup concept, the Data Dictionary validation, the complement to table_facilities, and the metadata-only caveat.

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 one-parameter lookup tool with no output schema, the description covers the key aspects: what it returns (programs referencing the table), validation, and scope (metadata only). It could explicitly state the output format (e.g., a list of program names) but the purpose makes this obvious. Overall, it is complete enough.

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 already provides 100% coverage of the single parameter 'table' with a descriptive example. The description does not add parameter-specific details, but the schema fully documents the semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb phrase ('Reverse lookup') and resource ('standard Ross ERP 8.0 programs referencing a given table'). It also distinguishes itself from the closely related sibling tool table_facilities, making the 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?

The description explicitly answers the intended use case ('what code touches this table?') and names a complementary tool (table_facilities) with a clear contrast. It does not mention other possible alternative tools or edge cases, but the guidance is sufficient for selection.

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