pull_artifact

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

Annotations declare readOnlyHint=true and openWorldHint=true, so the safety profile is already conveyed. The description adds meaningful context beyond this: it clarifies this returns editable fields for local editing, mentions behavior when NOWAIKIT_SYNC_DIR is set (writing one file per field and returning paths), and distinguishes this from update-set export. This enriches the read-only picture with concrete behavioral specifics. However, it doesn't disclose what happens to the fetched content or whether local writes are then synced back, and the local-sync side-effect behavior is somewhat under-specified.

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 compact three-sentence block that front-loads the core purpose ('Local sync: fetch an artifact's editable fields') before covering the conditional sync-dir behavior and clarifying what this is NOT. Every sentence earns its place, with the distinction-from-update-set clause preventing misuse. It is efficient and well-structured with no waste.

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

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

Given 2 fully-documented parameters, no output schema, and the sibling complement (push_artifact, sync_status, find_artifact, list_supported_artifacts), the description adequately explains the flow for a read operation. It covers the return content, the optional file-writing side effect, and the artifact-scope nature. The complexity is moderate and this description addresses the key use-case and the now-kit sync variant. There is no output schema so return value handling is reasonably implicit from 'returns content inline' and 'returns the paths'.

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 documents both parameters completely (table as artifact table with examples sp_widget/sys_script_include, sys_id as ID or resolvable name). The description adds framing context around these ('editable fields (e.g. template/css/script)') but the parameter semantics themselves are fully handled by the schema. Baseline 3 applies since the description goes slightly beyond by giving artifact examples and illustrating what editable fields means.

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 purpose is clearly stated with a specific verb+resource ('Local sync: fetch an artifact's editable fields...for local editing'). It distinguishes itself from sibling write tool push_artifact and from update-set export. It also clarifies the artifact type (e.g. Service Portal widget) which helps differentiate from get_script_include/get_business_rule (which fetch full objects vs editable fields in sync context). This is strong purpose clarity.

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 states it is for 'config/pro-code editing of a single artifact' and explicitly contrasts with update-set export ('not an update-set export'). This implies use when one wants local editing of a single artifact, distinct from broader sync flows. However, it does not explicitly discuss when to choose this over get_script_include, get_business_rule, or get_portal_widget, nor when to use push_artifact (the reverse), find_artifact, or validate_artifact. The conditional NOWAIKIT_SYNC_DIR behavior offers context but no explicit alternatives or exclusions for sibling fetch tools. Adequate but with room to be more explicit.

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