update_measure

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

With no annotations provided, the description carries the full burden. It does disclose that this is a mutating operation, enumerates which fields are affected, and states the return shape ('a dictionary containing success status and the updated measure details'). However, it omits error behavior when measure_name is not found, permission requirements, and whether updates are atomic or partial, which matters for a mutation tool with zero annotation coverage.

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 sentence is front-loaded and the returns line is useful, but the bulk of the description is a parameter enumeration that partially duplicates the schema's optional/type structure. The parameter list is justified given 0% schema coverage, yet the overall text is longer than needed and the redundant 'optional' markers could have been trimmed.

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 mutation tool with no annotations and no output schema, the description covers parameter meanings and the return value adequately. But it is incomplete: no failure modes, no prerequisites (e.g., must the semantic model be set?), no guidance on partial updates, and no explicit routing between this and create_measure/delete_measure. Workable, but with clear gaps.

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 0%, so the description must compensate, and it does: every schema parameter gets a semantic gloss ('dax_expression: New DAX formula', 'format_string: New display format string', 'is_hidden: New hidden status'), adding meaning beyond bare types and titles. It loses a point because the explanations are terse one-liners and 'ctx' is documented in the description but absent from the schema, creating a minor inconsistency.

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, 'Update an existing DAX measure in a semantic model,' names a specific verb (update) and resource (DAX measure), immediately distinguishing it from siblings like create_measure, delete_measure, get_measure, and list_measures. An agent can tell what this tool does 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 word 'existing' implicitly signals this tool is for modifying measures that already exist, which implies it should not be used to create new ones. However, the description never explicitly names alternatives or states when-not-to-use it, so an agent must infer the boundary against create_measure and delete_measure from context alone.

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