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

Annotations already carry readOnlyHint=false and destructiveHint=true, and the description is consistent with them. It adds value beyond the annotations by disclosing the spec_confirmed refusal behavior and the return contract (execution result or error message), which the annotations do not convey. 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?

Three sentences, each earning its place: the core purpose is front-loaded, followed by the critical gating condition, then the return behavior. Zero fluff or repetition of schema/annotation content.

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?

An output schema exists (covering the return contract) and annotations cover the safety profile (destructive, not read-only), so the description needn't repeat those. It covers purpose and the critical gate. The one notable gap is the parameters array semantics, which remain undefined in both schema and description; however, a correct basic invocation is still achievable with just code and spec_confirmed=true.

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. It explains spec_confirmed explicitly ('must be true or the tool refuses') and implies the code parameter (the C# code being sent), but it never clarifies the free-form parameters array — what it contains, whether it maps to method arguments, or its relationship to the code. This is only partial compensation for the absent 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 is highly specific: 'Send C# code to Revit for execution over the local TCP socket' names the verb, the resource, and the transport mechanism. This makes it easy to distinguish from siblings like list_tools, get_tool_choices, and run_tool without looking at their schemas.

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 invocation context by disclosing the refusal gate: 'Refused unless spec_confirmed=true'. This tells the agent when the call will fail and what precondition must be met. However, it does not explicitly contrast with alternatives such as run_tool or say when NOT to use it beyond the gate.

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 readOnlyHint annotation already signals a non-mutating operation, and the description adds useful behavioral detail beyond that: it returns parameter-name-to-options mapping and targets only parameters that need selection. No side effects, permissions, or error behavior are described, but for a read-only query tool with an output schema this is acceptable.

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 tight sentences with no filler: the purpose is front-loaded, the sequencing guidance is immediate, and the return format is stated exactly. Every sentence contributes a distinct, useful fact.

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?

With one simple parameter, an output schema, and read-only annotations, the description covers the essential workflow: discover choices before running. The only notable gap is the imprecise parameter meaning, and there is no mention of what happens if the tool is not yet solidified. These are minor given the low complexity and existing 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?

Schema description coverage is 0%, so the description carries the burden of explaining the 'name' parameter. It says 'of a solidified tool' but never explicitly states that name is the solidified tool's name; this is only implied. A clear mapping such as 'name = the name of the solidified tool' would have compensated for the empty schema, and its absence makes the parameter meaning ambiguous.

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 pairing ('Query Revit for dynamic parameter choices of a solidified tool') and adds the return shape, so an agent knows exactly what to expect. It also differentiates the tool from siblings by positioning it as the discovery step before run_tool, making its role 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?

It gives explicit when-to-use guidance: 'Call this BEFORE run_tool to discover available levels, family types, etc.' This is clear context for the primary use case. It does not enumerate when-not-to-use cases or name multiple alternatives, but the run_tool reference is sufficient for typical agent selection.

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 readOnlyHint annotation already communicates that this is a safe read operation, and the description adds the scope that only 'solidified' tools are listed. It does not describe any further behavioral traits such as ordering, filtering, or output limitations, but for a simple list tool with an output schema this is acceptable.

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, focused sentence with no filler or redundant wording. It conveys the core purpose efficiently.

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 zero-parameter read-only tool with an output schema, the description provides sufficient context for an agent to invoke it correctly. The only minor gap is that it does not clarify how this listing differs from the sibling get_tool_choices.

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 no parameters, and the schema is already complete with 100% coverage. The description reinforces that the tool lists all available tools without requiring inputs, which is consistent with the empty parameter set.

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 ('List') and the resource ('all solidified tools available for execution'), making the tool's purpose easy to grasp. However, it does not explicitly distinguish itself from the sibling get_tool_choices, which could plausibly serve a similar listing role.

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 no guidance on when to use this tool versus siblings like run_tool or get_tool_choices. There is no mention of the appropriate context, prerequisites, or why this tool should be selected over alternatives.

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 a refusal gate (spec_confirmed=true) and a required preceding call for dynamic params. The destructiveHint annotation already covers destructiveness, and the description adds concrete behavioral constraints without contradicting it.

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 short sentences; the main verb+object, the most important warning, and a concrete parameter example are packed with no filler. The critical prerequisites are front-loaded.

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 essential invocation path: call get_tool_choices for generated params, set spec_confirmed=true, and supply params JSON. With an output schema present and annotations covering safety, remaining gaps such as where names come from are minor.

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 example of params as a JSON object and spec_confirmed=true adds meaning to the otherwise bare schema, which has 0% coverage. However, it calls params a 'JSON object' while the schema declares a string type, which can mislead an agent into passing an object instead of a JSON-encoded string.

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?

States 'Execute a solidified tool by name with given parameters.' This names a specific verb and target and clearly differentiates from siblings like solidify_tool (creation), list_tools, and get_tool_choices.

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 explicit prerequisites: call get_tool_choices first for parameters with choices_from / source: query:*, and notes the tool is refused unless spec_confirmed=true. It does not explicitly compare with execute_code or list_tools, but the required conditions are 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the outcome (saving a reusable named tool) but does not disclose side effects, overwrite behavior, persistence, what counts as 'successful,' or how the tool relates to prior execution state. For a mutation-like tool, this is a significant gap.

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 and front-loaded, stating the core purpose in the first sentence and following with useful parameter format hints. There is no filler or redundant restating of the tool name.

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 6 parameters, no annotations, and an output schema that covers return values, the description still leaves important gaps: what 'source_query' means, how a successful code execution is identified, and any prerequisites. The agent has enough to attempt a call, but not to confidently ensure correct invocation. An output schema does not excuse missing parameter context.

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. It adds meaningful format details for 'parameters' ('JSON array of {name, type, description, source?, default?, choices_from?}') and 'tags' ('comma-separated tags'), which the schema does not provide. However, it leaves 'source_query' and the top-level 'description' field unexplained, and code/name are only self-evident from their names. Partial compensation only.

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 and resource: 'Save a successful code execution as a reusable named tool.' This clearly distinguishes it from sibling tools like execute_code (executes), run_tool (runs a tool), and list_tools (lists tools). An agent can immediately understand what this tool accomplishes.

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 phrase 'successful code execution' implies the tool should be used after code has been executed successfully, providing some contextual guidance. However, the description does not explicitly say when to use this tool over alternatives, nor does it mention exclusions or prerequisites. Usage context is implied rather than stated.

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