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

The annotation idempotentHint=true already covers idempotency. The description adds behavioral context by stating 'Does NOT require instance authentication', which is valuable for an agent deciding to invoke without credentials. However, it doesn't disclose whether the build produces specific artifacts or modifies the source tree, so it's not a full behavioral disclosure.

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, each earning its place: purpose, prerequisite, and explicit sequencing plus auth note. No wasted words, front-loaded with the primary action.

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

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

The description is complete for a simple build tool: it covers what, when, prerequisites, and auth requirements. It doesn't explicitly mention the output artifact, but the phrase 'application package' implies the result. With only two optional params and no output schema, the description provides adequate context 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% with both 'debug' and 'workingDirectory' having clear descriptions in the input schema. The description itself does not add parameter-specific meaning, but since the schema already fully documents them, the baseline 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 'Build a Fluent (ServiceNow SDK) application package from source code', which is a specific verb and resource combination. It also distinguishes itself from sibling tools by explicitly placing it 'after init_fluent_app and before deploy_fluent_app'.

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

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

Explicitly states 'Run after init_fluent_app and before deploy_fluent_app', giving clear workflow sequencing. It also specifies the prerequisite 'valid Fluent project directory with now.config.json' and notes that instance authentication is not required, helping the agent decide when to use it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds 'Lazily validates configured auth once', disclosing caching behavior, and lists the returned fields, which goes beyond annotation coverage. No contradiction with 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?

Two sentences, front-loaded with the main purpose, then behavioral details, then usage guidance. Every sentence adds value without redundancy.

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

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

For a simple read-only status check with an output schema available, the description covers purpose, behavior, and usage context completely. It even names the specific commands that require this check, making it self-contained.

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

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

The tool has 0 parameters, so the schema is fully complete (100% coverage). The description doesn't need to add parameter-level detail. It does mention the output shape, which adds some context, but the baseline for zero parameters is 4.

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

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

The description uses a specific verb ('Check') and resource ('ServiceNow authentication status'), clearly distinguishing it from sibling tools which are build/deploy/transform operations. It also states it returns a JSON with specific fields, reinforcing its purpose.

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

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

Explicitly states when to use (before any command that requires authentication) and lists the exact sibling commands (deploy_fluent_app, fluent_transform, download_fluent_dependencies, download_fluent_app), providing clear context and exclusion criteria.

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

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

The description explicitly warns 'CHANGES INSTANCE STATE', which aligns with and reinforces the destructiveHint=true annotation. It also adds behavioral context beyond the schema by noting authentication requirements and that these are instance-mutating operations via sn_cicd. It does not detail side effects or irreversibility, but given the annotations, this is adequate.

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

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

The description is four sentences and front-loads the core purpose and state-change warning. It packs essential contextual rules—app identification, Fluent project defaults, rollback requirement, and auth—without filler or repetition of the full schema. Every sentence contributes operational 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?

Given the 14-parameter tool and no output schema, the description covers the key non-obvious behaviors: action types, state mutation, app identification modes, defaulting behavior, rollback's mandatory version, and authentication. The schema already documents individual parameter details, so this high-level guidance is sufficient for safe and correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter logic not fully obvious from individual schema descriptions: 'inside a Fluent project both appSysId and appVersion default from now.config.json/package.json, and outside one both must be passed explicitly'. It also restates the rollback appVersion requirement, consolidating important conditional behavior.

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: 'Run a ServiceNow app-repo CI/CD operation via the sn_cicd API', and enumerates the exact action types: 'install, publish, or rollback'. This clearly distinguishes it from sibling tools like build_fluent_app or deploy_fluent_app, which target different stages of the app lifecycle.

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 contextual guidance: how app identity and version are resolved inside vs. outside a Fluent project, when appVersion is mandatory, and that auth is required. It does not explicitly name alternative tools or state when not to use this tool, but the context is clear enough for an agent to decide when to invoke 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?

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description explicitly warns that action='run' executes real ATF steps and changes records, while 'watch' and 'result' only read. It also discloses authentication requirements, adding meaningful context not present in 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 yet information-dense: it states the purpose, defines the three action modes, clarifies read vs. write behavior, and notes prerequisites in just a few sentences. There is no repetition of schema content 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?

For a 21-parameter tool with no output schema, the description covers the key decision axes: operation mode, target type, identifier strategy, side effects, and authentication. It delegates parameter-level details to the already-rich schema, which is reasonable, though a bit more on expected return shapes would make it fully self-contained.

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

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

Schema coverage is 100% with strong per-parameter descriptions, so the baseline is 3. The tool description adds semantic value by tying action values to progressId/resultId requirements and by explaining how target maps to suite/test identifiers, which helps disambiguate conditional parameter usage.

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: 'Run or inspect ServiceNow ATF tests through the sn_cicd API.' It clearly enumerates the target/action combinations and distinguishes this tool from sibling app build/query/deploy tools by focusing on ATF test execution and inspection.

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 actionable when-to-use guidance: use 'run' to start, 'watch' for an existing progressId, and 'result' for a resultId. It also clarifies that no Fluent project is required. It stops short of explicit 'when not to use' or named alternatives, but the guidance is otherwise 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 signal destructiveHint and idempotentHint, and the description reinforces this by calling out that it 'removes all compiled artifacts'. It adds value beyond annotations with the follow-up instruction and the authentication note, which are not present in the structured metadata.

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

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

The description is three sentences long, front-loaded with the primary action, and each sentence adds necessary information: what it does, the consequence, and the follow-up action. There is no redundant or irrelevant 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 destructive operation with no output schema, the description covers the essential context: what gets deleted, that it is destructive, what to do afterward, and that authentication is not needed. This is fully sufficient for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters. The tool description does not add additional parameter-specific meaning beyond what is in the schema, so it meets the baseline but does not exceed it.

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

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

The description clearly identifies the action ('Delete') and the specific resource ('build output directory of a Fluent (ServiceNow SDK) application'), distinguishing it from sibling tools like build_fluent_app or pack_fluent_app. It is concise and 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 implies when to use it by stating 'Run build_fluent_app afterward to regenerate', which ties it to the build workflow. It also notes that no authentication is required, providing useful context. However, it does not explicitly state alternatives or when not to use it, so it stops 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?

Annotations already note destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds valuable context about authentication auto-injection, the need for a prior build, and the option to prevent flow auto-publishing, which goes beyond the structured fields 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, directly gets to the point with the primary action first, and includes only essential information about prerequisites and a key parameter. No redundant or flowery language.

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

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

Given the tool's complexity, the description covers the necessary context: prerequisites, auth, and a critical deployment option. While it doesn't detail post-deployment outcomes or error handling, the rich schema and annotations fill those gaps adequately for a deployment tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; mentions of skipFlowActivation and auth mirror the schema descriptions. No extra param semantics are provided.

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

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

The description explicitly states the tool deploys a built Fluent application to a ServiceNow instance, using a specific verb and resource. It distinguishes itself from siblings by mentioning the prerequisite build via build_fluent_app, clarifying its role in the 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?

It clearly indicates when to use the tool: after a prior build via build_fluent_app, and specifies a key option (skipFlowActivation) that controls behavior. However, it does not explicitly contrast with alternative tools or provide 'when not to use' exclusions, but the context is sufficient.

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 annotations already indicate destructiveHint: true and openWorldHint: true. The description adds context about expanding the application to a directory and including metadata not present locally, but it does not explicitly disclose potential overwriting of local files. It does mention authentication auto-injection, which is helpful.

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, uses three sentences, and is front-loaded with the main purpose. Every sentence adds value: what it downloads, extra inclusion note, directory purpose, incremental mode, and authentication requirement. 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?

Given the tool's complexity (6 parameters, 100% schema coverage) and annotations, the description provides sufficient context for invocation. It covers the core purpose, directory semantics, incremental mode, and authentication. It does not elaborate on return values or failure modes, but no output schema exists and the tool seems straightforward for a download operation.

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

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

The schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra meaning to 'directory' by explaining it specifies where to expand the application, and to 'incremental' by explaining it downloads only changes since the last download, which goes beyond the schema.

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

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

The description clearly states the tool downloads application metadata from a ServiceNow instance to a local directory, with a specific verb and resource. It does not explicitly distinguish itself from download_fluent_dependencies, but the phrase 'application metadata' implies a different scope from dependencies.

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 when to use the tool by describing its core purpose and mentions incremental mode, but it does not explicitly name alternatives or exclusion scenarios. There is no direct comparison with download_fluent_dependencies or other sibling tools.

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

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

The description discloses authentication requirements (auto-injected from session or explicit), the scope of dependencies (tables/roles outside application scope via global config), and the purpose (set up type definitions). This adds behavioral context beyond the openWorldHint annotation, which itself signals external side effects. No contradiction found.

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: main action, prerequisite/auth info, and usage context. No filler, front-loaded with the primary verb and object. 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?

No output schema exists, but the description clarifies what gets downloaded (config and type definitions) and when to run it. For a parameter-light tool with a straightforward file-download purpose, this is sufficient for an agent to plan the task. Additional details like resulting file layout would be nice but not essential.

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?

Input schema coverage is 100% for all three parameters with descriptive text (auth, debug, workingDirectory). The description does not add parameter-level detail beyond the schema, but the schema already carries the 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 uses a specific verb 'Download' and resource 'configured dependencies from now.config.json and TypeScript type definitions'. It clearly distinguishes from siblings like download_fluent_app (which downloads the app itself) and init_fluent_app (which initializes the project).

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

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

Explicitly states when to run ('Run this after init_fluent_app to set up type definitions before development') and describes a specific use case for pulling outside-scope types via dependencies.global. It does not name alternatives, but this tool is unique among siblings, so exclusion guidance is less critical.

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 and idempotentHint=true, and the description reinforces this with 'Read-only; no authentication or active Fluent project required.' It adds extra behavioral context about the list and peek flags, explaining how they alter the output. This goes beyond the annotations by describing optional behaviors, though it does not detail any potential side effects (which are unlikely given the read-only nature).

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

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

The description is three sentences long, front-loaded with the primary purpose, and then efficiently covers capabilities, flags, and alternatives. There is no fluff—every sentence provides useful guidance, making it easy to parse quickly.

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

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

For a documentation-lookup tool with no output schema, the description fully covers behavior, parameters, alternatives, and prerequisites. It explains how to enumerate topics, peek, and switch formats, and it mentions that no active Fluent project is needed—critical for understanding this standalone read-only tool. The sibling context further clarifies the niche, making the description complete.

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

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

The input schema already provides 100% coverage, with detailed descriptions for every parameter (e.g., topic: 'Required unless list=true,' list: 'Combine with topic to filter the index'). The description largely restates these details without adding substantial new meaning, so it does not elevate the baseline of 3. It briefly reinforces list/peek/format but does not compensate for any missing schema coverage.

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

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

The description opens with a specific verb+resource: 'Look up Fluent SDK documentation for any API or guide.' It provides concrete examples of topics and keywords, and explicitly distinguishes itself from siblings by directing users to 'get-api-spec for metadata-type specifications and get-snippet for code examples.' This makes the tool's purpose unmistakable and well-differentiated.

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

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

The description explicitly states when to use this tool (for documentation lookups) and names alternatives for other use cases: 'Use get-api-spec for metadata-type specifications and get-snippet for code examples.' It also clarifies prerequisites by noting 'no authentication or active Fluent project required,' helping users decide when to call this tool without hesitation.

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 include destructiveHint=true and openWorldHint=true, which lowers the bar. The description adds context about authentication and source selection but does not disclose specific side effects (e.g., overwriting existing files or modifying the Fluent project). It doesn't contradict the annotations, but it also doesn't significantly elaborate beyond their safety signals.

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

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

The description is three sentences long, front-loaded with the primary purpose, then providing actionable usage modes. Every sentence earns its place without redundancy or fluff.

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

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

The description covers the main usage modes, authentication requirements, and parameter relationships. Given the tool's complexity (two sources, table hierarchy, optional id), it is fairly complete. It could mention what the output looks like or that conversion writes to the Fluent project directory, but the schema already documents directory and workingDirectory parameters, and there is no output schema to explain.

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 meaningful context beyond the schema by explaining that 'from' is for local files and omitting it pulls from the instance, and that 'table' can be combined with 'id' to target a specific record and its relationships. This goes beyond the raw 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?

Description uses a specific verb and resource: 'Download and convert XML metadata records from a ServiceNow instance or local path into Fluent source code.' It clearly distinguishes the tool from sibling tools like build_fluent_app or deploy_fluent_app by focusing on transformation of XML metadata into Fluent source.

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

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

Provides explicit usage guidance: 'Use from for local XML files, or omit to pull from instance' and 'Use table (SDK v4.7.0+) to transform by table hierarchy, optionally with id.' Also notes the authentication requirement. However, it doesn't explicitly mention alternatives or when not to use this tool in favor of a sibling tool, so it doesn't fully earn a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds the behavior that calling without arguments lists all types, which is useful context beyond the annotations. It does not describe the return format, but the output schema likely covers 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?

Three sentences, each earning its place: the first states the core action, the second explains the no-arg behavior, and the third provides usage context and alternatives. It is front-loaded and free of fluff.

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

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

Given the tool's simplicity (one optional parameter) and the presence of an output schema, the description is complete. It covers purpose, usage, and alternatives without needing to explain return values, which are handled by the output schema.

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

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

The schema already documents the single optional parameter with 100% coverage. The description adds meaningful examples ('business-rule', 'script-include') and clarifies that omitting the parameter lists all types, enhancing understanding of the parameter's role.

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

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

The description clearly states the action ('Fetch') and the resource ('Fluent API specification for a ServiceNow metadata type'), with concrete examples. It explicitly distinguishes itself from sibling tools by directing users to get-snippet for code examples and get-instruct for best practices.

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 tells the user when to use the tool ('before writing code') and provides explicit alternatives for related needs, naming get-snippet and get-instruct. It also explains how to list all metadata types by omitting the argument.

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

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

With annotations already declaring readOnlyHint=true and idempotentHint=true, the description need not repeat safety traits. It adds valuable context about what guidance is provided (patterns, conventions, common pitfalls), going beyond a generic summary and giving the agent an accurate expectation of the tool's output.

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

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

The description is two sentences, front-loaded with the core purpose, and every clause serves a purpose. It avoids redundancy and formatting issues, making it easy to parse quickly.

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

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

Given a single parameter, an output schema, and clear sibling differentiation, the description fully covers the essential context. The alternatives are explicitly named, and no additional return-value explanations are needed since an output schema exists.

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 covers 100% of the parameter with a description ('ServiceNow metadata type (e.g., business-rule, script-include)'). The description repeats the same example but adds no additional semantic detail beyond what the schema already provides, so baseline 3 is appropriate per the rubric.

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 ('Fetch') and resource ('instructions and best practices for creating a ServiceNow metadata type using the Fluent API'), and clearly distinguishes from siblings by naming get-api-spec and get-snippet as alternatives. This makes the tool's unique purpose unambiguous.

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

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

The description explicitly states when to use this tool (for instructions/best practices) and provides direct alternatives: 'For API specifications, use get-api-spec. For code examples, use get-snippet.' This gives clear guidance on choosing between related tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, establishing safety. The description adds useful behavioral details not in annotations: it returns the first available snippet without an id and provides additional snippet ids if more are available. This enriches understanding of the tool's output behavior.

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

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

The description is five sentences, all information-dense and front-loaded with the core purpose. It wastes no words, and every sentence adds value (purpose, behavior, alternatives).

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 tool with annotations and an output schema, the description covers purpose, usage, alternatives, and behavioral nuances. It provides all needed context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the optionality of 'id' and its effect ('Returns the first available snippet when called without an id'), and by giving examples for metadataType. This supplements the schema descriptions with behavioral semantics.

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

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

The description clearly states the tool fetches a Fluent code snippet for a ServiceNow metadata type, with concrete examples ('business-rule', 'script-include'). It also distinguishes itself from sibling tools by explicitly naming get-api-spec and get-instruct.

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 provides when to use the tool and when not to: 'For API specifications, use get-api-spec instead. For best practices, use get-instruct instead.' It also explains behavior when called without an id, which informs usage.

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

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

Annotations already provide openWorldHint=true and idempotentHint=false, setting the safety profile. The description adds behavioral context beyond annotations: the requirement that workingDirectory must be empty and that conversion from an instance requires auth. It doesn't fully enumerate side effects (e.g., files created or global changes), but given the annotation coverage, this is sufficient and consistent.

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

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

The description is three sentences: the first states the core purpose, the second explains mode-specific parameters, and the third adds a prerequisite and next-step pointer. There is zero fluff—every sentence contributes essential information, and it is front-loaded with the main action.

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

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

Given the tool's complexity (9 parameters, no output schema), the description covers the essential decision points (creation vs conversion), prerequisite (empty directory), and follow-up action (build_fluent_app). It doesn't describe the return value or detailed post-conditions, but the context provided is sufficient for an agent to select and invoke the tool correctly in most scenarios.

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 parameters are already documented individually. The description adds cross-parameter semantics by grouping parameters per intent and clarifying which are required in each mode (e.g., 'template' required for creation, 'from'+'auth' for instance conversion). This synthesis of parameter relationships goes beyond the 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 clearly states the tool's dual purpose: 'Initialize a new Fluent (ServiceNow SDK) application or convert an existing scoped application.' It uses specific verbs and distinguishes itself from sibling tools by mentioning 'After init, use build_fluent_app to compile,' which differentiates init from the build step.

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

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

The description provides explicit mode-selection guidance: 'Set intent to "creation" for a new app (requires appName, packageName, scopeName, template) or "conversion" to convert from an instance sys_id or local directory (requires from, and auth for instance conversion).' It also states the workingDirectory must be empty, offering clear context for when the tool can run. It doesn't explicitly exclude alternatives, but the workflow hint with build_fluent_app adds practical usage context.

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

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

The annotation already marks the tool as idempotent. The description adds that it does not require authentication and that it requires a prior build, which is useful behavioral context. It does not detail side effects like file overwrite, but idempotency provides some assurance.

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 concise sentences, front-loaded with the core purpose. No unnecessary words.

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

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

Given the tool's simplicity (3 optional params, no output schema, idempotent annotation), the description covers purpose, prerequisites, auth requirements, and output usage, making it adequately complete.

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

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

All 3 parameters have descriptions in the schema, so the description is not required to add param details. It does not, but the schema is self-sufficient.

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

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

Description clearly states the tool packages a built Fluent app into a zip artifact. It identifies the specific action (package), resource (built app), and output (zip for installation), distinguishing it from siblings like build or deploy.

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?

States the prerequisite of a prior build via build_fluent_app and indicates the zip is for manual installation, implying an alternative to automated deployment. However, it doesn't explicitly contrast with deploy_fluent_app or specify when not to use it.

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

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

Discloses read-only nature (reinforcing readOnlyHint), mentions authentication requirements, and adds extra behavior like 'unresolved path yields null rather than an error' in the select parameter. No contradiction with annotations; adds context beyond 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?

Description is a single, well-structured paragraph that front-loads the core purpose, includes authentication note, and provides an example—every sentence adds value without fluff or repetition.

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

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

For a tool with 16 parameters and a fully described schema, the description covers the essential usage pattern and return format. It doesn't explain pagination, but that's not critical given schema coverage and the mention of JSON envelope. Adequate for the complexity.

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

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

Schema has 100% description coverage (baseline 3). Description adds value by providing a concrete query example and noting SDK version constraints for the select parameter. This enriches parameter meaning beyond the schema.

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

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

Description clearly states the action (run a read-only query), the target (ServiceNow table via Table REST API), and the outcome (returns matching records as JSON envelope). It also distinguishes this tool as the query capability among siblings, which are all build/deploy/init operations.

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

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

Provides clear usage context: requires instance authentication (with auto-injection or explicit auth), and gives an example query. No explicit exclusion or alternative mention, but no alternative query tool exists among siblings, so this is adequate.

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 and idempotentHint, and the description adds operational behavior beyond that: it explains the two flags, the optional command parameter, and the lack of authentication/project requirements. This gives the agent a solid understanding of what to expect.

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

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

Two sentences, front-loaded with the primary purpose, then concise flag guidance and key constraints. No wasted words; 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 simple 2-parameter info tool with complete schema coverage and no output schema, the description covers all essential context: what it does, how to invoke it, valid flags, and prerequisites (none). It is fully sufficient for an agent to select and use 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%, so baseline is 3. The description adds value by giving examples (-v, -h, command: 'build') and clarifying that command is only used with -h, which goes beyond the schema's field descriptions.

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

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

The description clearly states the tool retrieves Fluent SDK version or help information, using a specific verb ('Get') and resource ('Fluent (ServiceNow SDK)'). It distinguishes itself from siblings that perform build/deploy/init operations by focusing on informational use cases.

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

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

The description gives explicit guidance for flag usage (-v for version, -h for help) and notes it does not require authentication or a project directory, which is clear usage context. It does not explicitly name alternatives among siblings, but the unique purpose implicitly guides selection.

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