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

Beyond the destructive annotation, the description discloses important behavioral effects: already-published decisions use new entries on their next call, the previous active version remains in use until activation completes, and outcome can be active, running, or failed. It also explains republish as a recovery operation for a destination that lost the published version.

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 purpose is front-loaded in the first sentence, followed by focused paragraphs on activation effects, outcome states, and republish. Every sentence adds operational meaning with no redundant filler.

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

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

The tool is a destructive activation operation, and the description covers activation effects, previous-version behavior, outcome states, and republish recovery. With annotations covering safety and an output schema covering return values, no critical agent-facing 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?

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning for republish and version behavior beyond the schema text. It explains that republish is for a destination that lost the active version, and clarifies wait_seconds through the running outcome state.

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 gives a specific verb and resource: make a lookup table version active by publishing its entries to MAS and CAS. It clearly distinguishes activation from editing or creating lookup tables, though it does not explicitly name sibling alternatives such as update_lookup_table or publish_decision_flow.

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 explains the key usage contexts: activating a version for rules, and using republish when a destination such as CAS lost the active version. It does not explicitly state when not to use this tool versus update/publish siblings, but the conditions for activation and republish are clear.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true): discloses that the whole batch is applied atomically ('all succeed or nothing changes'), that every operation is validated against the object catalog before any HTTP call with ALL failures reported at once, that placement/dataRoles are write-once and same-batch forward references fail, and that the ETag optimistic-concurrency handshake is retried once transparently. This is rich, non-obvious behavioral context an agent needs.

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?

Front-loaded with the core purpose before the detailed bullet list, and the content is dense rather than repetitive — the inline examples and layout recipes carry genuine information. It is nonetheless long, and some bullets (e.g. chart-title and grid-placement detail) sit near the edge of what a tool description should carry versus delegating to describe_report_objects.

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 8-parameter batch-mutation tool with ~60 object types, this covers everything an agent needs: atomicity, pre-flight validation, concurrency handling, save-as mode, layout/titles, and where to verify results. An output schema exists, so return-value detail is correctly omitted.

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 real meaning beyond it by explaining the operations array's element structure, the valid operation keys, placement semantics (geometric vs flow-order, same-batch reference limits), and layout/title conventions. The one gap is that save-as flags are documented only in the schema, not reinforced in the prose.

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

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

States a specific verb and resource ('Apply an ordered batch of operations to a report') and immediately characterizes scope ('the authoring workhorse'), then enumerates the concrete authoring actions (add pages, add objects, set parameters, swap data sources). This clearly separates it from siblings like get_report_outline, export_report, and create_report, so an agent can identify it without opening the schema.

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 routes the agent to complementary tools for sub-tasks ('Call describe_report_objects for each operation's shape', 'get_castable_columns to map columns onto those roles', read back with get_report_outline, verify with export_report). It gives clear context for when this is the right tool, but never states a when-not/exclusion case (e.g. which edits belong to other tools instead), so it stops just 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?

The description goes well beyond the annotations by explaining what the assignment actually does, what downstream catalog facets read it, and that 'assigning the same term to the same column twice is reported, not duplicated.' This gives concrete idempotency semantics beyond the idempotentHint annotation, with no contradiction to the annotations.

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 purpose is front-loaded in the first sentence, and each subsequent sentence adds non-redundant context: the distinction from term creation, the downstream consumers of the assignment, and duplicate behavior. There is no filler or unnecessary 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?

Given the fully documented schema, output schema, and annotations, the description supplies the non-obvious context an agent needs: what the assignment does, what reads it, and how duplicates are handled. Nothing material 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?

Schema description coverage is 100%, so the schema already documents all parameters including term_id, term_name, table_name, column_name, and resource_uri. The description does not add parameter-level meaning beyond that, so the baseline score 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 opens with a specific verb and resource: 'Assign a business term to a table column,' and immediately conveys the operational consequence ('the step that makes a term govern data'). It also distinguishes itself from create_glossary_term by explaining that creating only defines a word, so an agent can tell assignment apart from term definition.

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

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

The description clearly implies when to use this tool: after a term exists, when the goal is to attach it to a column rather than just define it. It also ties the effect to downstream tools like list_table_terms and list_term_assets, giving useful context. However, it does not explicitly point to unassign_glossary_term as the removal alternative or state when not to use this tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's job is lighter. The description adds the useful scoping constraint that only running jobs can be canceled, but it does not disclose potential side effects or failure behavior 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 one short sentence that immediately communicates the operation and adds the key qualifier 'running' beyond the title. There is no redundancy or wasted 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 simple one-parameter, destructive operation with full schema coverage, an output schema, and relevant annotations, the description is mostly sufficient. It clearly identifies the target and state constraint, though it could be more complete with a note about cancellation effects or error conditions.

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 job_id as the ID of the job to cancel, so schema coverage is 100%. The description adds no additional parameter-level meaning beyond what the schema already provides, 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 states a specific action (cancel) and a specific resource (a running job), making the tool's purpose immediately clear. It also distinguishes this tool from sibling job-related tools like submit_batch_job, get_job_status, list_jobs, and get_job_log.

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

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

The description gives no guidance on when to use this tool versus alternatives, such as checking job status first with get_job_status or retrieving logs with get_job_log. It only implies the tool is for running jobs, but does not explain prerequisites, ordering, or when cancellation is not appropriate.

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

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

Annotations already mark this as read-only and idempotent, and the description adds substantial behavioral context beyond that: it returns a recommendation to run catalog_run_adhoc_analysis instead of an empty profile when profiling is missing, resolves resource_uri via resourceId like catalog_find_instance, and documents that instance_id takes precedence when both are supplied.

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

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

The description is front-loaded with the core action and output in the first sentence, then adds fallback behavior and parameter-selection details in short, purposeful paragraphs. Every sentence contributes distinct information without 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 read-only download tool with rich annotations, full schema coverage, an output schema, and an important edge case, the description covers the result format, unprofiled-table behavior, parameter precedence, and relevant sibling workflow. No critical usage information 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 describes all three parameters, but the description adds critical non-redundant semantics: the caller must provide either instance_id or resource_uri, instance_id takes precedence if both are given, and resource_uri supports a search → profile → download workflow without handling an instance id. This materially improves parameter understanding 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 a specific verb and resource: 'Download a catalog table's data dictionary and profile as CSV.' It also distinguishes the tool from siblings like catalog_run_adhoc_analysis by describing the unprofiled-table fallback, so an agent can clearly identify what this tool does.

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

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

It states when the tool is appropriate (downloading metadata/profile) and names the alternative catalog_run_adhoc_analysis for the unprofiled-table case. It also provides clear guidance on choosing instance_id vs resource_uri, including the workflow benefit of resource_uri. It does not exhaustively compare to all catalog siblings, but the guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavior beyond annotations: it performs lookup by resourceId, returns the instance id plus profile attributes, and exposes whether the asset has been profiled via analysisTimeStamp. This gives the agent a good mental model of what will happen without contradicting the annotations.

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

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

The description is front-loaded with the core purpose, then builds context efficiently. Every sentence earns its place: one sentence for purpose, one for relation to catalog_search and key return fields, one for the downstream tool. The use of backticks for identifiers keeps it scannable without unnecessary verbosity.

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

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

For a single-parameter lookup tool with a rich output schema and annotations covering safety, the description is complete. It explains the input, the output, the relationship to sibling tools, and the practical use case. Nothing an agent needs to decide whether to call this tool 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?

Schema coverage is 100% and the schema already documents resource_uri with an example. The description adds meaning by explaining where the URI comes from (search hit or CAS table path) and connecting it to the resourceId lookup used by the profiling workflow. This goes beyond a bare schema description, though the relationship between resource_uri and resourceId could be slightly clearer.

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

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

The description opens with a specific verb and resource: 'Resolve the catalog instance for a source-asset URI.' It immediately distinguishes the tool from catalog_search by explaining that catalog_search finds assets by free text and facets while this tool resolves the instance id that profiling/download tools require. The purpose is unmistakable even without reading the schema.

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 when-to-use guidance: use it when you already hold a resource URI from a search hit or a CAS table path, and use it before calling catalog_download_table_profile. It also names the alternative, catalog_search, and explains the difference in lookup style. This is strong routing guidance for 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?

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description discloses the delayed profile-attribute write, defines profile_ready via analysisTimeStamp, relates it to the gate catalog_download_table_profile uses, and adds the information_privacy/NLP enrichment behavior. This is substantial behavioral context, not schema repetition, and it does not contradict the annotations.

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 summary sentence is front-loaded and the second paragraph earns its length: it explains the race condition, defines the readiness flags, references the download gate, and ends with the exact polling action. No filler sentences are present.

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

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

With only one parameter, an output schema, and safety annotations already supplied, the description covers the subtle timing gap, the meaning of profile_ready and information_privacy, and the correct invocation sequence. Nothing needed to call and act on this tool 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?

Schema description coverage is 100% and the sole job_id parameter is already documented as 'The analysis job id returned by catalog_run_adhoc_analysis.' The tool description adds only an indirect note about 'when the job carries a resource,' so the schema carries the parameter-semantics burden; 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 opens with a specific verb-resource pair: 'Get the status of an ad-hoc analysis job, and whether its profile is ready.' It then sharpens the distinction from generic job-status tools by explaining that terminal status is not sufficient, so an agent can tell this apart from get_job_status and knows it is the readiness gate before catalog_download_table_profile.

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 and a direct usage pattern: 'Poll until profile_ready is true, then download.' It also explains the race condition that motivates the tool. It does not explicitly name a when-not-to-use alternative such as get_job_status, but the polling instruction and download caveat make the intended usage unmistakable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by explaining that each record reports run status and metadata population counts (enumerated/added/updated/removed), which helps the agent interpret results without contradicting annotations.

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

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

The description is compact and front-loaded with the core purpose, followed by a concise explanation of the record contents and the practical use case. Every sentence contributes meaningful information without repetition or 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?

Given the output schema exists, annotations cover the safety profile, and all parameters are documented in the schema, the description provides sufficient contextual glue: why to call it, what it returns at a high level, and how it relates to catalog_run_agent. Nothing essential for calling it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including defaults for limit and start and the agent_id reference to catalog_list_agents. The description adds high-level context about run history but does not add significant parameter-level meaning beyond what the schema provides.

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: 'Get the execution history of a catalog agent's runs.' It clearly distinguishes itself from sibling tools like catalog_run_agent by framing the purpose as confirming that a run started via catalog_run_agent finished and what it changed.

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

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

The description provides a clear use case: use this tool to confirm whether a catalog agent run finished and what metadata it changed. It references catalog_run_agent as the initiating tool, giving contextual guidance, though it does not explicitly list exclusions or alternatives beyond that.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and non-open-world, so the safety profile is fully covered structurally. The description adds useful domain context (agents crawl a server/library to collect metadata) but discloses nothing beyond that about cost, permissions, or result volume, so it is only a modest addition over the annotations.

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, front-loaded with the core action, then a compact definition of the resource, then sibling routing. No filler; every sentence earns its place.

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?

A read-only list tool with an output schema (so return values need no prose), full 100% parameter documentation, and named sibling alternatives. Nothing an agent needs to select and invoke it correctly is missing.

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

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

Schema description coverage is 100%: limit, start, and filter_name each carry their own description including defaults and substring-match semantics. The description adds no parameter detail, so the baseline of 3 applies since the schema does all the work.

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

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

States a specific verb (List) plus resource (SAS Data Governance discovery agents), then defines what those agents actually do (crawl a data source to discover assets and collect metadata). This clearly separates it from catalog_run_agent and catalog_get_agent_history without the agent needing to open 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?

Explicitly routes to alternatives: catalog_run_agent to start an agent, catalog_get_agent_history to inspect a run, which tells the agent when this tool is NOT the right one. It stops short of stating the explicit trigger for calling this one (e.g. 'call before running an agent to obtain its ID'), so it is clear context rather than full when/when-not 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?

Annotations provide no meaningful hints (all false), so the description carries the burden of behavioral disclosure. It explicitly states the job runs asynchronously and may take a while, which is critical for an agent deciding whether to wait or poll. It also reveals that the three NLP parameters are enabled by default and drive semantic enrichment around informationPrivacy, nlpTerms, nlpTags, and mostImportantFields, including a performance tradeoff for disabling them. This goes well beyond the schema and annotations.

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

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

The description is well-structured and front-loaded with the core action, followed by the profile contents, then the async workflow, then the NLP parameter guidance. Each sentence adds useful information and there is no filler. It is slightly longer than minimal, but every paragraph serves a distinct 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?

For a tool with 8 parameters, an output schema, and asynchronous behavior, the description is complete: it explains what the job produces, how to retrieve the result, what the default NLP parameters do, and when to consider disabling them. The output schema covers return values, and the schema covers parameter syntax. Nothing needed for correct invocation or follow-up polling 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 input schema already documents all 8 parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially for the NLP booleans: it explains they drive semantic enrichment and affect job duration, and it clearly names the asset fields they populate. It does not add detail for every parameter, but the schema handles those adequately.

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

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

The description opens with a specific verb and resource: 'Submit an ad-hoc analysis (profiling) job for a table in the catalog.' It then clarifies what the job produces (data dictionary, column statistics, data-quality metrics) and explicitly distinguishes it from sibling tools like catalog_download_table_profile and catalog_get_adhoc_analysis. An agent can tell exactly what this tool does and how it fits into the catalog workflow.

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 explains the asynchronous workflow: submit the job, receive a job id, and poll catalog_get_adhoc_analysis until the profile is ready. It also names catalog_download_table_profile as the tool whose output this job computes, giving context for when a precomputed profile might be the alternative. It does not explicitly state when to use one over the other, but the polling instruction and sibling references provide strong practical guidance.

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

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

The description discloses key behavioral traits beyond annotations: the run is asynchronous, results are applied in the background, and completion requires polling. It also states the cannot-stop limitation, which is critical operational context. No contradiction with the annotations.

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

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

The description is concise and front-loaded, with the core action in the first sentence. Every subsequent sentence adds useful context: background application, polling, and the stop limitation. 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?

For a single-parameter tool with an output schema and annotations, the description fully covers what the tool does, how it behaves, how to track it, and its limitation. Nothing call-critical 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?

Schema description coverage is 100%, and the agent_id parameter is already documented as the ID of the agent to run with a pointer to catalog_list_agents. The main description adds no additional parameter-level meaning, 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 uses a specific verb and resource: it 'Starts a catalog discovery agent run' and explains the agent will crawl its data source and populate/refresh metadata. This clearly distinguishes it from related tools like catalog_list_agents or catalog_get_agent_history.

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 poll catalog_get_agent_history to track completion, which gives the agent a follow-up path. It also notes that the API can only start an agent, not stop one, preventing misuse. It doesn't explicitly enumerate all sibling alternatives, but the usage context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds worthwhile context by specifying what each hit contains (resource_uri and attributes map with example keys), which goes beyond the annotations, but doesn't cover pagination behavior beyond element semantics.

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?

Front-loads purpose and environment scope, then details return shape and query grammar. The grammar section is appropriately detailed for a complex query language, though slightly long; every section earns its place.

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 a rich query grammar and follow-up actions to sibling tools, the description covers purpose, return shape, and grammar. Output schema exists, so return values need not be explained. Slightly missing explicit exclusion guidance, but otherwise complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value by documenting the query grammar — wildcards, facets, ranges, the + operator, and combination syntax — which meaningfully exceeds what the schema's one-line description provides.

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

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

States a specific verb (search) and resource (SAS Data Governance catalog assets) and names concrete asset types. It distinguishes itself from server/library-scoped siblings by explaining that the catalog is a metadata index across the whole environment, so assets can be found without knowing server/library first.

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?

Explains what the tool is good for (finding assets without knowing server/library) and routes the agent to catalog_search_helper for facet discovery, plus get_report/get_castable_data for follow-up actions. It lacks explicit when-not-to-use guidance versus list-based tools like list_reports or list_castables, but provides clear 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context: no facet returns available facets, while a facet name returns suggested/valid values that actually exist, which helps the agent understand what the tool will do.

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

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

The description is compact and front-loaded with a clear summary, followed by two sentences that explain the two modes and the downstream purpose. Every sentence contributes useful guidance without 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?

Given the simple parameter set, full schema documentation, output schema presence, and read-only annotations, the description is complete. It explains when to call, what the two behaviors are, and how the results should be used in catalog_search.

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 extra meaning by explaining that facet values are 'the asset types or review statuses that actually exist' and that results are intended for building catalog_search queries. It does not add detail for limit or query, but those are already well documented in 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 a specific verb and resource: 'Discover how to search the catalog: list facets, or values for one facet.' It clearly defines two modes and refers to catalog_search, making it easy to distinguish from the sibling catalog 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 explains when to call with no facet versus with a facet, and tells the agent to use the results to build precise catalog_search queries. It does not explicitly state when not to use the tool, but the helper role relative to catalog_search is clear.

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

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

Annotations declare a non-read-only, non-destructive, non-idempotent mutation; the description adds real behavioral detail beyond that — that child rules travel with a rule set, and that a lookup table copy carries the entries of its active (or specified) version and is not itself active. It doesn't cover naming collisions or permission requirements.

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?

Front-loads the supported types in the first sentence and spends the remainder on the two non-obvious caveats. Slightly fragmented line breaks, but 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?

Output schema and annotations carry the return/safety burden, and the description covers the non-obvious edge cases (excluded types, version handling). Folder default behavior is delegated to the schema, which documents it, so nothing critical 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: revision_id is described as accepting a version ID or label, and the interaction between revision_id and the lookup table's active version is spelled out.

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

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

States a specific verb (copy) plus the exact set of copyable asset types, and explicitly names the two types that cannot be copied. An agent can distinguish this from siblings like create_* or get_decisioning_asset immediately.

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?

Gives a clear when-not rule (custom functions and function categories cannot be copied) and clarifies which version of a lookup table gets copied. It does not explicitly route the agent to an alternative tool for the unsupported types, but the usage context is unambiguous.

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

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

Annotations already declare destructiveHint: true and idempotentHint: false. The description adds the return payload shape ({status, id, name, source_report_id}) and the copy-and-replace workflow, going beyond what annotations provide. It does not contradict the annotations, though it could have explained that on_conflict='replace' may overwrite an existing report.

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, front-loaded with the core action and result. The use-case sentence earns its place, and the return-format sentence is compact. No wasted words.

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

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

Covers purpose, usage patterns, and return shape; with schema handling parameters and annotations handling destructive behavior, little is missing. A minor gap is not explicitly calling out that on_conflict='replace' can overwrite an existing report, though that is present in the schema.

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

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

Schema description coverage is 100% with detailed descriptions for all four parameters, so the baseline applies. The description does not add parameter-level details beyond what the schema already states.

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

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

States a specific verb ('Copy'), resource ('Visual Analytics report'), and outcome ('returning the copy's id'). This clearly distinguishes it from sibling report tools such as create_report, delete_report, and get_report.

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 concrete use cases: tailoring a report to a new audience and the copy-and-replace pattern, explicitly naming apply_report_operations as the follow-up. It lacks explicit exclusions or alternative copy tools, but the context is clear enough for an agent to select it.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, closed-world mutation, so the safety profile is covered. The description goes beyond them with a genuinely valuable silent-failure disclosure: malformed expressions are accepted by the API but produce DS2 code with a missing left-hand operand, plus the boolean variable convention. It omits operational prerequisites such as lock/revision state before mutation.

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?

Front-loads the action in the first sentence and follows with two dense, non-redundant pitfall notes rather than restating field names. Slightly long given everything else lives in the schema, but no sentence is 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?

With full schema coverage, an output schema present, and annotations covering the safety profile, the description only needed to add domain pitfalls — which it does. The remaining gap is the mutation workflow context (locking a ruleset revision, whether the target must be unlocked), which would help an agent avoid a failed call.

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 earns extra credit by adding expression-format semantics not in the schema (variable name must be embedded in the expression, booleans compared as = 0/= 1). It does not clarify conditional chaining or lookup-table referencing beyond what the schema already states.

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

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

States a specific verb and resource ("Create a new rule") and pins the scope with "inside an existing SAS Business Rules rule set", which cleanly separates it from create_business_ruleset and update_business_rule. An agent can identify the operation without reading the schema.

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?

"New rule" vs the sibling update_business_rule implies the create-vs-modify split, and the description's mention of rule sets holding multiple rules gives context. However, it never explicitly says when to use this instead of update_business_rule, nor does it state prerequisites (e.g. that the rule set may need to be locked for a revision before adding a rule is possible).

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?

Beyond annotations declaring a non-read-only, non-destructive create operation, the description discloses key behavior: the rule set is always folder-scoped, omitted folder uses a deployment default, no default causes refusal, and the result reports the storage folder. This gives the agent important operational context and error handling guidance.

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

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

The description is short and front-loaded: the create action comes first, followed by the required follow-up, then folder-storage edge cases. Every sentence carries actionable information without 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?

Given the output schema and annotations, the description supplies the remaining context an agent needs: dependency on create_business_rule, folder fallback behavior, refusal handling, and result folder reporting. Parameter-level details such as name length and signature structure are adequately covered by the schema.

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

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

Schema coverage is 100%, so the schema already documents all four parameters in detail. The description adds meaningful semantics for the folder parameter by explaining default behavior and refusal conditions when folder is omitted, though it does not add equivalent detail for signature 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 verb and resource: 'Create a new SAS Business Rules rule set in a SAS Content folder.' It also distinguishes rule-set creation from rule creation by instructing the agent to follow up with create_business_rule to populate the set.

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 workflow guidance: an empty rule set cannot be used in a decision flow, so create_business_rule should follow. It also explains folder omission behavior and when the call is refused. It does not explicitly compare against update/get/list siblings, so it falls short of full when/when-not 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?

Beyond annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses real behavior: Viya parses the code to derive the signature, Python cannot declare types so they remain unknown unless supplied, and the result's status/errorMessage indicate parse success. That post-creation validation behavior is exactly the kind of context annotations cannot carry.

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?

Purpose is front-loaded in the first sentence, followed by per-language specification details in the order an agent would need them. The formatting is dense and skimmable, with only minor redundancy in restating the type/signature rules.

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 6-parameter creation tool with an output schema, the description covers the essentials: required code shape per language, when signature details matter, folder defaulting (in schema), and how to detect a parse failure. It omits what happens on name collision or overwrite and whether any permissions/locking are needed before creation.

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?

With 100% schema coverage the baseline is 3, but the description goes further by explaining what the loosely-typed `signature` objects must contain for Python (dataType for every input and output) versus what they add for DS2 (descriptions and lengths). It also ties code structure to the code_type enum, which the enum alone does not convey.

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 first line states a specific verb, resource, and the three supported code types (DS2, Python, SQL), so an agent can immediately tell this is a creation tool for code files rather than a decision flow or ruleset. It does not name the sibling it is not (update_code_file), so differentiation from the modify path relies on the name alone.

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?

Usage is implied by the purpose statement and reinforced by format-specific requirements per code_type, but there is no explicit 'use this when... / use update_code_file instead when...' guidance. The closest to a rule is the folder note ('omit to use the default folder; if there is none, ask the user'), which appears in the schema rather than as routing 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?

Annotations declare non-readonly, non-destructive, non-idempotent, closed-world. The description adds meaningful behavioral context beyond that: the function is compile-checked on creation, and there is a propagation delay ('a few seconds to be visible to validate_decision_expression'). It omits what happens on failed compilation (error vs. partial creation), keeping it from a 5.

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?

Front-loaded with the verb and resource, followed by a concrete code example and the visibility caveat. Every sentence carries information; the inline DS2 snippet is longer than strictly necessary but earns its place as a template. No wasted preamble.

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

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

An output schema exists, so return values needn't be described, and annotations cover the safety profile. The description fills the important gaps – compile validation, naming rule, propagation delay. It stops short of describing failure behavior or required permissions for a mutation tool, so a minor gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds semantics: the `code` value is exactly one DS2 method whose name becomes the function name, which is not in the schema. That name-derivation rule is the key insight an agent needs and raises the score.

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?

Starts with a specific verb+resource: 'Create a DS2 custom function that rule expressions can call, after checking that it compiles.' An agent can distinguish this from update_custom_function and validate_custom_function by the create intent. Sibling differentiation is implicit (validate/update variants exist) rather than called out explicitly, so not a 5.

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 explains the creation context – the code is a DS2 method used by rules in expressions like risk_band(credit_score) – and hints at verification via validate_decision_expression. However, it never explicitly states when to use this versus update_custom_function or validate_custom_function, and there are no exclusions. Usage is implied rather than stated.

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

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

Annotations already declare write, non-idempotent, non-destructive, non-open-world, so safety framing is covered. The description adds real behavioral context beyond that: the decision is always stored in a SAS Content folder, the call is refused with no default folder, the result's folder field reports placement, and assignment strings are stored literally rather than evaluated. It does not mention auth/permission requirements, but on balance it adds substantive value.

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?

Front-loaded with the purpose statement and mode selection, then organized by step kind with bolded headers. It is long, but nearly every sentence carries operational detail; the worked example is the only section an expert agent could skim.

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

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

An output schema exists so return values need no explanation, yet the description still flags steps_report and variables_added. For a 7-parameter, deeply nested construction tool it covers folder behavior, step wiring, revisions, mappings and validation cross-references — nothing an agent needs 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?

Schema coverage is 100%, yet the description goes well past it: the steps array is free-form (additionalProperties: true) in the schema, and the description supplies the entire step-kind grammar — assignment quoting rules, model id/mappings and output variables, branch range inclusivity and non-overlapping case constraints, condition DS2 expressions, and add_missing_variables default behavior. This is exactly the semantic lift a description should provide.

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

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

States a specific verb and resource ('Create a SAS Intelligent Decisioning flow') and enumerates the step kinds it accepts, which clearly separates it from siblings like update_decision_flow, create_business_ruleset, or create_segmentation_tree. An agent can identify it as the flow-construction tool without opening the schema.

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 routes between the two input modes ('give the flow as steps ... or, as before, rule_set_steps') and cross-references validate_decision_expression, list_registered_models and list_decisioning_assets. It also prescribes the fallback behavior when no default folder exists ('ask the user which folder to use'). Missing is any explicit statement of when to prefer this over update_decision_flow or creating assets individually.

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?

Beyond the minimal annotations, the description discloses major behavioral quirks: attribute values are converted to Viya's accepted spelling, validation fails with attribute-specific errors before the HTTP call, terms are published by default even though the underlying API defaults to draft, and name uniqueness is enforced case-insensitively among siblings. This is far more than the annotations provide.

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

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

The description is front-loaded with a one-line purpose, then uses bold labels and bullets to organize conversion rules, publish behavior, and uniqueness constraints. Although longer than average, every sentence carries operational information an agent needs to avoid failed calls.

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 8 parameters, a custom attributes object, a surprising publish default, and sibling workflow dependencies, the description covers all critical invocation details: prerequisites, value formats, failure behavior, publishing, and uniqueness. An output schema exists, so not restating return values is acceptable.

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

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

Although the input schema has 100% coverage, the description adds important meaning to the attributes parameter by specifying accepted Python forms for booleans, multi-selects, dates, date-times, and times. It also clarifies the publish parameter's default and effect, and explains name uniqueness for the name parameter beyond the schema text.

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 opening sentence uses a specific verb and resource: 'Create a business term in the SAS Business Glossary.' The rest of the description refers to term-specific behaviors (term type, attributes, publish) that separate it from sibling tools like create_glossary_term_type and update_glossary_term.

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

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

It explicitly instructs callers to invoke get_glossary_term_type first because term types can impose mandatory attributes. It also names update_glossary_term(publish=true) for promoting drafts and notes that drafts are visible under list_glossary_terms only with include_drafts, giving clear workflow direction.

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

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

Annotations only carry safety hints; the description adds meaningful behavior: it generates attribute identifiers the API requires, and it warns that the API rejects omission with a vague error. This gives an agent useful insight beyond structured fields.

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

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

The description is front-loaded with the core purpose and uses a compact bullet list for attribute types. It is longer than minimal but every section adds necessary detail about the API's expectations.

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 an output schema present and complete parameter documentation, the description covers the unusual API quirks and design context sufficiently. Minor omissions such as explicit exclusions or edge cases are acceptable given the sibling list and schema richness.

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 parameters, so baseline is 3. The description goes further by specifying the valid attribute types, optional attribute keys, and how allowed_values interacts with select types, which clarifies the loosely typed attributes 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 opening sentence 'Create a term type — the template that fixes what a term must carry' names the exact verb, resource, and purpose. It clearly distinguishes this from sibling tools like create_glossary_term and update_glossary_term_type by explaining that a term type defines attributes every term must hold.

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

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

The description explains the design context, noting that without this tool types can only be created in the SAS UI, so MCP users can design glossaries through it. It doesn't explicitly list when not to use it or name alternatives, but the role is clear enough.

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

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

Goes well beyond the annotations: discloses that rules only see an active version, that activation publishes to MAS and CAS in 'usually seconds', and that wait_seconds governs how long to block. It also surfaces non-obvious validation constraints (key texts up to 256 chars, values up to 512, numbers stored as text, keys unique, empty value behaves like a missing key) that no annotation or schema field conveys.

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?

Front-loads the core purpose, then layers activation semantics and constraints. Dense but every paragraph carries information; the embedded rule-JSON examples for `lookup` and `lookupValue` are the only portion that could arguably be trimmed for an agent that already knows the ruleset format.

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 8-parameter creation tool with annotations and an output schema, this covers purpose, activation lifecycle, and data constraints well; return values need not be explained. It omits failure behavior — e.g. what happens on duplicate keys or name collisions — which an agent creating assets would benefit from knowing.

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, and the description earns above that by adding real meaning: it explains the runtime consequence of `activate` (MAS/CAS publication) and puts hard limits on the shapes accepted by `entries` and the key/value content. The remaining parameters (folder, key_label, value_label, description) are left entirely to 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?

Opens with a specific verb and resource ('Create a SAS Intelligent Decisioning lookup table') and immediately defines what the resource is — keys plus a stored value per key. This distinguishes it clearly from sibling creators like create_value_list, create_business_ruleset, or create_segmentation_tree without needing to inspect any schema.

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 routes on the activation decision: pass `activate` to publish immediately, or 'call activate_lookup_table once the entries are final' — naming the concrete sibling alternative. It does not address the update path (update_lookup_table) or when to prefer a value list instead, 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?

Beyond the annotations, the description discloses that the tool verifies table memory scope before proceeding and returns an actionable error otherwise. It also explains how the data-table URI is constructed. This adds meaningful behavioral context that the annotations and schema do not provide. It does not mention the auto_run default side effect, but the core verification behavior is clearly disclosed.

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

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

The description is compact and front-loaded: the main purpose appears first, followed by a dense but relevant prerequisite paragraph. Every sentence contributes either purpose, precondition, error behavior, or parameter context. No filler or repetition is present.

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

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

For a 9-parameter creation tool with a full schema and output schema present, the description covers the critical prerequisite, verification behavior, and URI construction. It does not explain the auto_run side effect or the meaning of prediction_type, but the schema already handles parameter definitions. The main gap is the lack of mention that creation may trigger automatic pipeline runs.

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 schema already documents all parameters. The description adds extra value by explaining that the data-table URI is built from server_id/caslib_name/table_name and by emphasizing the memory/scope requirement for the table. This helps the agent understand relationships between parameters beyond their individual schema descriptions.

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

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

The description opens with a specific verb and resource: 'Create a new AutoML pipeline automation project from a CAS table.' This clearly distinguishes the tool from siblings like list_ml_projects, run_ml_project, and other create_* tools. The source is specified as a CAS table, which immediately orients the agent.

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 the precondition that the training table must be loaded into CAS memory at global scope, and references promote_table_to_memory and list_source_tables as the relevant helpers. It does not explicitly contrast with list_ml_projects or run_ml_project, but the prerequisite and pointer to alternative preparation tools provide strong when-to-use guidance.

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

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

The description adds meaningful behavioral details beyond the annotations: the atomic creation behavior, the empty default 'Page 1' prepended before operations, and the created summary carrying object names/labels that follow-up placement and exports target. These are non-obvious side effects an agent needs to know. It does not contradict the destructiveHint or readOnlyHint annotations.

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

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

The description is dense but well-structured, front-loading the core purpose and then layering in return semantics, behavioral caveats, and verification guidance. A few details are repeated or could be trimmed given the output schema exists, but every sentence adds functional value.

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

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

For a tool with four parameters, an output schema, and a destructiveHint annotation, the description covers all the important operational aspects: creation modes, atomicity, default page behavior, return shape, follow-up editing, and verification guidance. There are no critical gaps that would prevent an agent from invoking 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 beyond the schema by explaining that operations can 'bind data, add pages, add objects' and are applied atomically at creation, which clarifies the operations parameter's role versus using apply_report_operations later. It also frames the result as an empty shell when operations are omitted.

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

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

The description states a specific action ('Create a Visual Analytics report') and a concrete deliverable ('return its id for further edits'), distinguishing it clearly from sibling tools like list_reports, get_report, and delete_report. It also clarifies the two creation modes: an empty shell or a full atomic build via operations.

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

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

The description explicitly tells the agent to feed the returned id to apply_report_operations for further editing, and to verify page-by-page with export_report rather than a whole-report export. It also explains when the operations parameter is preferable, namely to avoid leaving an empty report behind if later edits fail.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent create. The description adds real behavioral substance: how nodes evaluate (first match wins, then ``next`` or ``outcomeName``), how values are parsed, and that outcomes either assign or run DS2 code. It doesn't state what happens on name collisions or failure modes, keeping it at 4.

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?

Purpose is front-loaded, then structural semantics, then a compact example, then the sibling routing — a sensible order. The value-syntax sentence and example are dense but earn their space; a little of the prose could be trimmed without loss.

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 9-parameter create with nested objects, the description covers the hardest parts (node tree traversal, value syntax, outcomes, folder default behavior). Secondary params like matrices, code_files, and boolean_expressions rely on their schema descriptions, and an output schema exists, so the residual gap is small.

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%, but the critical nested objects (`node`, `outcomes`, `matrices`) are only `additionalProperties: true` in the schema — the description supplies the actual shape, value mini-language, and a concrete worked example. That is meaningfully beyond what the schema conveys.

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?

Opens with a specific verb+resource: "Create a SAS Intelligent Decisioning segmentation tree." That immediately distinguishes it from update_segmentation_tree and from create_segmentation_tree_from_table, which is named later as the alternative.

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 routes large, table-driven trees to create_segmentation_tree_from_table, which is the key selection decision an agent faces here. It stops short of full when/when-not guidance (e.g. no mention of prerequisites, permissions, or duplicate-name behavior), so 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?

Annotations only declare the non-read-only, non-destructive, non-idempotent posture; the description adds real behavior: the source is exactly one of rows/file_path/caslib+table, local file reads are gated by an env flag, duplicate CSV headers become _2/_3, and the response reports counts and conflicts rather than the (potentially huge) tree. No auth or rate-limit context, but the disclosure goes well beyond the annotations.

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?

Front-loaded with the one-line purpose, then layered paragraphs for split semantics, source selection, and the return summary. Four paragraphs for 15 parameters is justified, though the split paragraph could be tighter and repeats some field-level detail already in the schema.

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 15-parameter, 3-required builder tool this covers what an agent actually needs: which source to supply, how to pre-stage Excel, the default-folder caveat ('if there is none, ask the user'), and that the response is a summary, not the tree. The output schema carries the rest.

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 earns above that by stating the mutual-exclusivity rule between the three source modes and by explaining how key_columns order drives testing and how lower_bound vs exact reshape branch values in ways the enum alone does not convey.

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?

Specific verb+resource with scope: 'Build one segmentation tree from a strategy table: one row per branch, a column per decision key.' The 'from table' framing plus the FICO/TRIAD/Blaze export context implicitly separates it from create_segmentation_tree, but that sibling is never named, so the agent must infer the split.

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?

Says when this applies ('This is how a FICO-style strategy export (TRIAD, Blaze) becomes a SAS Intelligent Decisioning tree') and routes to two prerequisites — upload_data for Excel sheets and the ALLOW_LOCAL_FILE_UPLOAD gate for CSV. It does not state when to prefer create_segmentation_tree instead, which is the main remaining ambiguity.

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

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

Annotations already disclose that this is a non-read-only, non-destructive, non-idempotent, closed-world mutation, so the bar is lower. The description adds useful entry semantics and numeric range syntax, but does not address uniqueness constraints, permissions, or what happens on duplicate names.

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 compact sentences, front-loaded with the action and resource. The definition and range syntax each earn their place with 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?

An output schema exists and parameter descriptions are complete, so the description needn't explain return values. It covers the core concept and entry syntax but omits sibling routing, which is a minor gap for a create tool with clear schema support.

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 baseline is 3. The description goes beyond the schema by explaining that entries are values or ranges and by documenting the 'v>=630' range syntax, which is meaningful for the 'entries' 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 gives a clear verb and resource ('Create a value list') and explains what a value list is. It does not explicitly distinguish this tool from close siblings such as create_lookup_table or update_value_list_entries, so it falls short of the top score.

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

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

The description mentions domain context (segmentation tree variables and rule conditions) but gives no explicit guidance on when to use this tool versus alternatives like update_value_list_entries or create_lookup_table. No exclusions or prerequisites are stated.

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

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

Annotations already declare destructiveHint and idempotentHint. The description adds 'Permanently' to reinforce irreversibility and narrows the target to a single rule within a rule set, but does not disclose additional behavior such as effect on the parent rule set or response on repeated deletes.

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?

A single focused sentence with the action and object front-loaded; no filler or repetition of structured fields.

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 two-parameter delete operation, the description, 100% schema coverage, idempotent/destructive annotations, and presence of an output schema cover the essentials. A brief note on prerequisite existence or effect on the ruleset would round it out, but nothing critical 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?

Schema coverage is 100% and both parameters already have clear descriptions, including the important guidance that ruleset_id expects a UUID, not a name. The tool description itself adds no parameter information beyond what the schema provides, so 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?

States a specific action ('Permanently delete') and a specific resource ('a rule from a SAS Business Rules rule set'), clearly distinguishing it from sibling tools like delete_business_ruleset or update_business_rule.

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 should be used when a rule must be permanently removed, and 'permanently' signals irreversibility, but it does not explicitly contrast with update/get/list alternatives or state any prerequisites or exclusions.

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

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

Annotations already mark this as destructive and non-read-only; the description adds meaningful context by stating the deletion is permanent and that deletion of a referenced ruleset fails. This goes beyond the structured annotations without contradicting them.

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 filler. The primary action is stated first, and the crucial warning is placed immediately afterward. Every sentence earns its place.

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 one-parameter destructive operation with annotations and an output schema, the description adequately covers the critical precondition and failure mode. An agent can correctly decide whether to call this tool or first verify decision-flow references.

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 100% description coverage, including a clear explanation that ruleset_id is a UUID and not a name. The tool description itself adds no additional parameter-level detail, so the high schema coverage justifies the baseline score 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 verb 'delete' and the specific resource, 'SAS Business Rules rule set,' which distinguishes it from siblings like delete_business_rule and delete_decision_flow. The phrase 'Permanently delete' makes the action 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 gives an explicit precondition: only call once the rule set is confirmed unused by any decision flow, and it warns that deletion fails if still referenced. It does not name specific sibling tools to use for checking dependencies, so it stops short of full alternative 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the description needs to add value beyond that. The word 'permanently' clarifies that deletion is irreversible rather than a soft delete or trash operation, and the parameter note '(not its name)' discloses that supplying a name will not work — both are genuine behavioral facts not present in the annotations.

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 eight-word sentence with the action front-loaded, and the parameter description packs three pieces of guidance into one compact sentence. There is no filler, repetition of schema details, or redundant phrasing.

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 tool with full annotations (destructive, idempotent, read-only), an existing output schema, and a parameter description covering the main pitfall (UUID vs name), the definition is nearly complete. The only gap is unspecified cascade behavior, such as whether revisions or publish state affect deletion, which would be nice but is not essential at this complexity level.

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 decision_id description goes beyond a simple field label by specifying the required format (UUID), stating a negative constraint (not its name), and naming the sibling tool that returns both identifiers. This materially helps an agent invoke the tool correctly on the first attempt.

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: 'Permanently delete a SAS Intelligent Decisioning flow.' The qualifier 'permanently' adds meaningful nuance beyond a generic delete, and the resource is precise enough to distinguish this from sibling deletes like delete_business_ruleset, delete_glossary_term, and delete_report.

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 main description gives no explicit when-to-use or when-not-to-use direction. However, the decision_id parameter description supplies indirect usage guidance by clarifying that a UUID is required, not a name, and pointing to list_decision_flows as the discovery path. This covers the prerequisite but omits exclusions such as alternatives for reversible deletion or interaction with lock/publish states.

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?

Beyond the annotations' destructiveHint, the description discloses that all revisions are destroyed, that referential-integrity checks cause Viya to refuse the delete in several distinct cases, and that a lookup table referenced by rule sets is rejected with the blocking rule sets named. This is exactly the non-obvious behavior an agent needs before attempting a destructive call.

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 destructive scope is front-loaded in the first sentence and the refusal semantics follow. The final sentence is slightly convoluted ('refused here, naming them: Viya would delete it and leave those rules invalid') but every sentence carries distinct 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?

With an output schema available and full schema coverage, the description need not explain return values, and it adequately covers destruction scope and refusal conditions. The remaining gap is how to obtain a valid asset_id and how this differs from the sibling delete tools.

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

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

Schema coverage is 100% and the asset_type enum enumerates every valid value, so the schema carries parameter meaning on its own. The description adds no syntax, format, or ID-discovery guidance beyond what the schema already documents, making the baseline 3 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 states a specific verb and resource — permanently delete a piece of decisioning content and all its revisions — which tells an agent exactly what is removed. It does not, however, distinguish this from near-name siblings such as delete_business_ruleset, delete_business_rule, or delete_decision_flow, so the boundary between 'decisioning asset' deletion and those targeted deletes must be inferred.

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?

Usage is only implied: you call this to permanently remove a decisioning asset. The description is rich on when the call will be refused (in-use rule sets, code files, non-empty function categories, referenced lookup tables) but gives no explicit guidance on when to prefer this tool over the more specific delete_* siblings.

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

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

Beyond the destructiveHint and idempotentHint annotations, the description discloses concrete side effects: assignments to columns are removed while columns remain, there is no cascade, and the existence of children is a hard block with an exact error message. This is exactly the behavioral context an agent needs before invoking a destructive 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 front-loaded with the core action and then organizes caveats in a clear order: impact, precondition check, no-cascade rule, and remediation steps. The longer length is justified because every sentence conveys a distinct, decision-relevant fact for a destructive operation.

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 one-parameter destructive tool, the description covers side effects, prerequisites, failure modes, error text, and workarounds. The output schema exists, so return value documentation is not required, and the description leaves no material gap for an agent to 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 coverage is 100% and the only parameter term_id is already described as 'The glossary term UUID.' The description does not add new meaning about how to obtain or format term_id, but it also does not need to; the schema carries the required semantic weight.

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 opening sentence uses a specific verb and resource: 'Permanently delete a business term.' This clearly distinguishes the tool from sibling glossary operations such as delete_glossary_term_type and update_glossary_term, while the rest of the description reinforces that it operates on a term and its assignments.

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 when-to-use and when-not-to-use guidance: check list_term_assets before deleting because a term with assigned assets is in use, and do not attempt deletion when the term has children ('cannot be deleted at all'). It also names actionable alternatives: delete the subtree leaf-first via list_glossary_terms(parent_id=...) or re-parent with update_glossary_term.

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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses a key behavioral consequence: deleting the type takes the attribute definitions of terms using it with it. It also reveals that the tool refuses by default and only proceeds with force, which is not obvious from the annotations alone.

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

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

The description is compact and front-loaded: it states the core action first, then adds necessary caveats and instructions in just three sentences. Every sentence earns its place; there is no redundant content.

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

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

For a destructive tool with two parameters and full schema coverage, the description is complete enough. It explains the refusal behavior, the destructive side effect, the recommended prerequisite check, and the force option. The output schema is available, so return values do not need to be described.

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 for both parameters, including clear descriptions for term_type_id and force. The description adds context around force (passing it when you have already decided), but it largely duplicates the schema's semantic content rather than introducing new meaning.

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

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

The description opens with the specific action and resource: 'Delete a term type.' This clearly distinguishes it from sibling tools like delete_glossary_term (which deletes a term, not a term type) and from create/update glossary term type tools. It leaves no ambiguity about what the tool does.

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

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

The description explicitly states when the tool will refuse (while terms still use the type), what to do instead (check with list_glossary_terms and move/delete those terms first), and when to use the force parameter (if you have already decided). This provides actionable guidance and clears up the main decision point for using the 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?

Annotations already mark this as destructive and idempotent. The description adds useful context beyond that: it deletes the report's content, there is no per-object undo, and the API returns specific statuses like not_found and delete_failed. This enriches the behavioral model without contradicting annotations.

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

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

The description is compact and front-loaded with the core action, followed by only the most decision-relevant behavioral details: no undo, copy-first workaround, and return statuses. Every sentence adds value and nothing is redundant.

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 one-parameter destructive tool, the description covers the scope of deletion, irreversibility, a practical workaround, and expected return states. With annotations providing destructiveness/idempotency and an output schema available, an agent has enough context to invoke this tool correctly.

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

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

The sole parameter report_id is already fully described in the input schema with 100% schema description coverage. The description does not add extra meaning to the parameter itself, which is acceptable since the schema provides sufficient semantics.

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

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

The description clearly states the specific verb-resource pair: 'Delete a Visual Analytics report and its content.' This aligns with the tool name and distinguishes it from other sibling delete tools (e.g., delete_decision_flow, delete_business_ruleset, delete_glossary_term) by explicitly targeting reports.

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 usage context by noting there is no per-object undo, and suggests deleting and rebuilding or copying first as the way to discard an unwanted report. It implies copy_report as an alternative for preservation but does not explicitly name it or define exclusion conditions.

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