Insert Metadata Record

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds genuinely non-redundant behavior: the write goes through the form in a specific application and update set, the record and its capture are read back, and three classes of targets are refused. Score should be higher than 3 – the refusals and the script-permission gate are real behavioral context beyond annotations. A 5 is more accurate: the description discloses guardrails (protection, ACL, script execution permission) and post-write verification that the annotations cannot convey.

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 purpose, then mechanism, then refusals. Dense but every clause carries information. Slightly heavy syntax (the long parenthetical list of code kinds) costs a bit of readability.

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 11-parameter mutation tool with no output schema, the description covers the write path, the verification/read-back, and the refusal conditions an agent must anticipate. It does not describe failure modes beyond refusal (e.g. what happens when the update set is not in progress), but the schema covers that constraint.

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 every parameter, including the update-set working-set requirement and the initial_query equality-term format. The description adds only that the application and update set are "named", which is already implied. 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?

Opens with a specific verb and resource ("Insert application metadata") and enumerates concrete examples (script include, business rule, UI action, property). It also states the mechanism (writes through the record's form in the named application and update set) and the read-back. It does not explicitly name insert vs update_metadata_record / batch_create_records as alternatives, so sibling differentiation relies on the verb 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?

Gives real when-not guidance: refuses protected files, the platform's own schema tables, and access controls, explicitly routing ACL work to the ACL tools. Adds a session-permission condition for code-bearing writes. It does not say when to prefer batch_create_records or update_metadata_record instead, which is the main remaining gap.

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