dataverse_is_component_customizable

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

Annotations provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety context is already clear. The description adds substantial behavioral context beyond that: the exact response shape (flat payload, single property named after the function), fallback behavior when future formats change, omission rather than null when no verdict is found, echoing raw_response, and HTTP 400 error behavior for mismatched GUIDs. The warning against reading missing is_customizable as false and the customizability nuance (managed properties can block specific edits even when the verdict is true) are valuable operational caveats the annotations could not 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?

The description is long but every paragraph earns its place: opening recommendation, function call specifics, response format, false/true semantics, the non-obvious system component behavior, and error identification. The first sentence is a clear front-loaded purpose statement. Paragraphs are short with bolded key phrases (BEFORE, DO NOT ASSUME, is_customizable) that aid scanning. The only minor redundancy is the sentence about component_type codes being echoed back as component_type_name, but it directly supports the 'mismatched code easy to spot' point, so no waste. This is efficient density, not padding.

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 pre-flight check with an output schema present, the description is complete. It covers what the tool does, when to use it, how to interpret both true and false verdicts, the exact payload shape, error behavior, and even addresses a common wrong assumption (system components). The presence of an output schema means return-value documentation isn't the description's job, and the description deliberately does not over-explain the output. The combination of annotations, rich schema param descriptions, and this behavioral narrative leaves no practical questions unanswered.

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 parameters already have strong descriptions (component_id explains NOT a solution id and includes concrete examples; component_type lists common values and links to Microsoft docs). The description adds crucial guidance beyond the schema: the component_type codes are the same set dataverse_analyze_dependencies uses, the resolved name is echoed back to catch mismatches, and the error semantics when component_id doesn't match a component. Given schema coverage is 0% in the structured sense but the description and schema complement each other well, and the description adds meaningful interpretive context, this earns a 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 opens with a specific verb and resource: 'Check whether a solution component can be customized BEFORE trying to edit it.' It clearly distinguishes this pre-flight check tool from sibling update/delete tools and from read-only introspection tools like dataverse_analyze_dependencies (which shares the component_type code set). The resource (solution component) and the scope (customizability pre-check) are explicit 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?

Explicitly states when to use: 'Run this first when editing anything you did not create yourself' and lists the exact write tools that benefit (dataverse_update_table, dataverse_update_column, etc.). It also gives behavioral guidance about interpreting results: a false answer means managed solution lock, while true is not a guarantee because managed properties can still block edits. It even warns not to assume system components answer false and provides example verified results. This is textbook when-to-use-this-vs-alternatives guidance.

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