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

No annotations are present, so the description must carry the full burden. It describes the output contents (views, actions, C# code, helper methods) but does not explicitly state that it is read-only or non-destructive, nor does it mention any side effects or limitations. It is informative 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 (two sentences), front-loaded with the core purpose, and every sentence adds value. There is no redundancy 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?

With no output schema or annotations, the description carries the load of explaining what is returned. It does so by listing the key content areas (views, actions with C# code, helper methods). It could be slightly more detailed about response format, but it is adequate for an agent to 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 input schema already describes both parameters (name and project) with 100% coverage. The tool description adds little beyond implying that 'name' identifies the controller. Baseline of 3 is appropriate given the 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 the resource (one controller) and exactly what it returns: views, actions with actual C# code, and helper methods. It distinguishes itself from siblings like xaf_search and xaf_overview by focusing on deep controller internals.

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 an explicit use case: 'Use when asked what a button or command actually does.' This gives clear context for when to use the tool, though it does not 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It prominently discloses a non-obvious behavioral trait: properties rendered by these editors do not show the control their type implies, and the business class gives no indication. This adds valuable context beyond a simple resource listing.

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: the first defines the scope of editors, and the second delivers an important caveat in caps. Every sentence earns its place, with no filler 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?

Given the simple optional parameter and the absence of an output schema and annotations, the description covers the key behavioral trap and defines what types of editors are included. It could explicitly state what the tool returns (e.g., a list of editor names or settings), but the critical warning makes it sufficiently complete for likely use cases.

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

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

The schema fully describes the sole optional 'project' parameter with a clear description, so the baseline is 3. The tool description adds no additional context about how this parameter affects results, but it does not need to because the schema already covers it completely.

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's focus on custom property/list editors and reconfigured built-in editors, which distinguishes it from siblings like xaf_controller and xaf_model. However, it lacks an explicit action verb such as 'list' or 'get', relying on the resource name to imply the tool's 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 provides explicit guidance to consult this tool before describing or changing UI appearance, and highlights a critical caveat about misleading assumptions. It does not mention alternative tools or when not to use it, so it stops short of offering full decision 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?

With no annotations provided, the description carries the burden of indicating the tool's behavior. It discloses the full detail returned and implicitly signals a read-only operation via 'Use before writing or changing'. However, it does not explicitly state side effects or permissions, though likely unnecessary for this context.

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

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

Two sentences, front-loaded with a clear definition of what the tool does, followed by a concise usage directive. No filler.

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

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

Despite lacking an output schema, the description thoroughly enumerates the return content and provides a clear usage context. It is sufficient for an agent to know when and how to use 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 already provides 100% coverage, including type and description for each parameter. The description adds no additional parameter-level guidance, so the baseline of 3 applies.

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

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

The description clearly states the tool returns full detail of a single business entity, enumerating the categories of information included. This is specific and distinguishes it from sibling tools like xaf_search or xaf_overview, which likely provide broader or partial views.

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 to use this tool before writing or changing code that touches an entity, which establishes a clear 'when to use' context. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full differentiation guidance.

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

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

With no annotations, the description carries the disclosure burden. It clearly states these blocks ran once and never again, establishing a read-only historical nature, and the caution about current code adds interpretive context. It does not mention output format, but that is less critical.

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: the first defines the resource, the second provides usage guidance. The wording is slightly dense but efficient, with no wasted 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?

For a tool with one optional parameter and no output schema, the description adequately covers purpose, usage, and behavioral context. It does not describe return values, but the use cases make clear the tool returns historical migration information.

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' is already fully described in the schema (100% coverage), and the description adds no additional parameter-level details. This matches the baseline of 3 when the schema handles the 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 identifies the resource as updater blocks that ran once during database upgrades, which clearly distinguishes it from sibling tools about current code. It lacks an explicit verb like 'list' or 'show', but the noun phrase and usage guidance communicate its role as a historical reference.

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 states when to use: when asked about column origins, legacy data provenance, or changes between releases. It also warns against reasoning from current code because it produces plausible wrong answers, effectively guiding the agent away from inappropriate 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 provided, so the description carries the full burden. It does disclose that behavior is XML-defined and cannot be inferred from C#—a valuable insight. However, it doesn't state whether the tool reads or writes, what side effects occur, or what output to expect. This ambiguity is significant for a tool with 'customizations' in its scope.

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: the first lists the tool's scope compactly, the second provides a crucial caveat. It is front-loaded with the domain and keeps the warning high-priority. No wasted words or redundant structure.

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?

This tool operates in a complex domain (XAF model customization) with no output schema and no annotations. The description tells you what the tool covers but not what it returns, whether it mutates state, or how it relates to the many sibling tools. The XML caveat is helpful but insufficient for confident 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 only parameter 'project' is already fully described in the schema ('Project name, when several are configured.'). Since schema coverage is 100%, the description adds no new semantic value, and the baseline of 3 applies. No extra usage details are given for the parameter.

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

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

The description clearly identifies the resource (Model Editor .xafml customizations) and enumerates specific content areas (captions, list/detail views, columns, filters, app options). However, the verb is implicit ('customizations' rather than 'get' or 'edit'), so it doesn't crisply state the action. It does distinguish itself from sibling tools by focusing on .xafml model behavior.

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 'IMPORTANT' statement gives a clear directive: check this tool before concluding how a screen behaves because behavior exists in XML, not C#. This implies when to use it, but it doesn't explicitly name alternatives or exclusions. Still, the usage context is strong enough to guide an agent.

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 transparency burden. It does disclose a key behavioral trait—that the lists are exhaustive and authoritative—which is valuable. However, it does not mention other behavioral aspects such as performance implications, response format, or whether it reads from a cache or scans files, leaving some transparency gaps.

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. The first sentence encapsulates the tool's content, and the second provides usage and behavioral guidance. There is no redundant or filler text, making it well-structured and efficient.

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 an overview tool with no output schema, the description provides a solid sense of what the response will contain (complete lists of key components). It stops short of detailing the exact result format or organization, but the content scope is clear enough for the agent to infer 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 input schema fully documents the single 'project' parameter with a clear description, so schema coverage is 100%. The tool description adds no additional parameter semantics, so it does not go beyond the schema baseline.

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 defines the tool as an overview of the entire XAF application, listing ORM, module setup, and exhaustive enumerations of entities, controllers, actions, and navigation groups. It distinguishes itself from sibling tools by emphasizing it is the complete index and should be called first for whole-app questions.

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 states 'Call this first when asked anything about the application as a whole', giving a direct usage trigger. It also implies the tool serves as a definitive existence check ('if something is not in them, it does not exist'), which guides when to rely on its results versus diving into specific sibling tools.

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

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

No annotations exist, so the description carries the burden. It discloses the cache-discarding behavior, the deferred effect ('on the next query'), and the caveat about automatic file change detection. It omits details about side effects or permissions, but for a cache refresh tool, the description is fairly transparent.

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 tight sentences: first states the action, second gives the usage condition. 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?

Low complexity (one optional param, no output schema). The description tells what happens, when to use it, and why it exists. Fully adequate for an AI agent to decide and 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?

Schema description covers 100% of the single parameter, giving the project name and its optionality. The tool description does not add parameter-specific meaning, but the baseline of 3 applies since schema already documents the parameter well.

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 ('Discard cached analysis and re-read the source') on a specific resource (the analysis cache). This clearly distinguishes it from sibling xaf_* tools, which focus on searching, overviews, entities, etc.

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 tells when to use: 'only needed if you believe the cached view is wrong,' and provides context that the server auto-detects changes, implying regular use is unnecessary. This is direct when-to-use guidance with an implicit alternative (do nothing).

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 burden. It adds a key limitation: 'Says explicitly when the list is a lower bound because users can also design reports at run time.' This is extra behavioral context beyond the raw purpose. It does not mention side effects or auth, but the tool is clearly read-only in nature.

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 no wasted words. Purpose is front-loaded, usage is provided, and the limitation is appended concisely. 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?

For a simple tool with one optional parameter and no output schema, the description covers what the tool returns, when to use it, and a caveat about completeness. Nothing essential is missing for an agent 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?

Schema description coverage is 100% for the single parameter, so the schema already documents the 'project' parameter. The description adds no additional parameter-specific guidance, matching the baseline for high 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 states a specific verb and resource: 'Reports the application registers in source' and details what it covers (what each report is over, filter/expressions, parameters dialog). This clearly distinguishes it from sibling tools like xaf_search or xaf_entity, even without naming them.

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

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

Explicitly states when to use: 'Use when asked what a report shows, why its numbers differ from a screen's, or before writing a new one.' However, it does not mention when not to use it or name alternative tools, so it falls short of 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 provided, the description carries the full burden of behavioral disclosure. It details what the tool returns (validation rules with messages, conditions, appearance rules, calculated properties) and implies a read-only query. It does not explicitly state side effects or return format, but the level of detail is strong.

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 only three sentences and every sentence serves a distinct purpose: defining the resource, specifying when to use it, and explaining parameter narrowing. It is front-loaded with the most important information and contains no filler.

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

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

For a two-parameter tool with no output schema, the description adequately captures content, usage, and parameter filtering. It does not mention empty responses or error handling, but that is not critical for an agent to select 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?

Schema description coverage is 100% with both parameters fully described in the input schema. The description adds a small reiteration for 'entity' ('narrowed to one entity') but does not need to compensate for any schema gaps, so the baseline of 3 applies.

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

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

The description clearly states what the tool does: it returns the business rules the application enforces, specifically enumerating validation rules with messages and conditions, conditional appearance rules, and calculated properties. This goes beyond a generic resource name and effectively distinguishes the tool from sibling tools like xaf_model or xaf_entity.

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 when asked what the system requires, forbids, or computes,' providing a clear when-to-use directive. It also notes optional narrowing by entity, which adds practical usage guidance beyond the schema.

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 what is searched (entity names, validation messages, etc.), that it is case-insensitive, and that it returns what matched and where. It does not state side effects or permissions, but as a search tool, the read-only nature is implied and adequately 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?

Two sentences, each earning its place. Front-loaded with the verb 'Search', followed by scope and usage context, with no redundancy or fluff.

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

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

The description is complete for a simple search tool. It covers purpose, usage, and return behavior, and no output schema means it needn't explain return structure beyond what is stated.

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 clear descriptions for each parameter. The tool description reinforces the 'kind' parameter by listing examples (entity, property, controller, etc.) and gives a concrete query example, but it adds minimal new information 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 opens with 'Search the whole application for a term' which clearly states the verb and scope. It enumerates specific resource types (entity, property, controllers, actions, etc.), distinguishing it from sibling tools like xaf_entity or xaf_controller.

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

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

It explicitly says 'Use when you know roughly what you are looking for but not where it lives' and provides an example. It gives clear context but does not mention exclusions or alternative tools, falling short of a fully explicit when-not/alternatives 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 transparency burden. It discloses the critical fact that most views are generated from business classes and not present in C# or .xafml files, preventing the agent from mistakenly reading files. It also reveals that omitting the view returns a screen list, a behavioral trait not visible from the schema.

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

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

The description is three sentences that front-load the core definition, then add an important caveat, then provide usage context. Every sentence contributes new information with no filler or repetition of schema 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?

Given the tool has no output schema and no annotations, the description gives a complete picture: what data the tool returns (controllers, actions, match reasons), how to invoke it (with or without a view), a critical gotcha about generated views, and concrete use cases. This is sufficient for an agent to correctly select and 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 documents both parameters (view, project) with 100% coverage, including default null and case-insensitivity. The description reinforces the view parameter's behavior by explaining the effect of omitting it (list all screens) but adds no new meaning for the project parameter. This meets the baseline for high schema coverage without major additional semantic value.

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

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

The description clearly defines the tool as showing what controllers and actions are loaded for a screen, with a specific resource (view) and detailed output (why each matches, which actions appear). It also explains the no-view invocation to list all application screens, distinguishing it from sibling tools like xaf_controller or xaf_model. This goes beyond a vague verb to explain the exact output scope.

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

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

It gives explicit use cases: 'Use before changing a controller, adding an action, or answering what a screen does.' It also explains the no-view pattern to list screens. However, it does not name alternative tools or specify when not to use it, so it's strong but not fully 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, the description takes the full burden of behavioral disclosure. It successfully discloses a important limitation: calls the trace cannot follow are reported explicitly, and an empty list has a meaningful interpretation. It does not explicitly state whether the tool is side-effect free, but the read-only affordance of a trace is strongly implied.

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

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

The description is three dense sentences with no filler. It opens with a concise definition of the tool, then quickly gives usage criteria, and ends with an important nuance about the completeness of the path.

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

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

For a complex exploration/walkthrough tool with no output schema and no annotations, the description covers the needed invocation context: starting points, scope, traversal boundaries, citation by file and line, and interpretation of missing-boundary results. It gives enough structure for an agent to know both when and how to call 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 input schema covers all three parameters with descriptions, so schema coverage is 100%; the baseline is 3. The description only reinforces the required 'from' parameter's valid starting points without adding behavior or details about 'depth' or 'project' 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 states a specific action—'Trace e one business process end to end'—and specifies what the trace covers: what runs, execution order, touched entities, and governing rules. The phrase 'rather than what exists' distills the tool from sibling existence/search tools, so selected against and invocation are 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 to use this path 'when asked HOW something works' and gives concrete examples like 'how does approval work' and 'what happens when I press this'. It also contrasts it with what-exists questions, giving an explicit when-to-use and when-not-to-use distinction.

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