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

With no annotations provided, the description carries the full burden of behavioral disclosure. While it states this is an 'add' operation (implying mutation), it doesn't disclose important behavioral traits: whether this requires specific permissions, whether it's idempotent, what happens if the facet already exists, or any rate limits. The description mentions the return format but doesn't explain potential error conditions or side effects.

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 well-structured with clear sections (Args, Returns) and uses bullet-like formatting. It's appropriately sized at 8 lines total. Every sentence serves a purpose: the opening statement defines the tool's purpose, the Args section documents parameters, and the Returns section shows output format. There's minimal wasted space.

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 the complexity (5 parameters, mutation operation, many siblings) and complete lack of annotations, the description provides basic but incomplete coverage. The presence of an output schema (shown in Returns) helps by documenting the response format, but the description doesn't address key contextual gaps: how this tool relates to siblings, what an 'attribute facet' conceptually is, or behavioral constraints. For a mutation tool with 0% schema documentation, this is minimally adequate.

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?

With 0% schema description coverage, the description provides some parameter context but doesn't fully compensate. It lists all 5 parameters with brief explanations, giving meaning to spec_id, location, attribute_name, value, and cardinality. However, it doesn't explain the significance of 'applicability' vs 'requirements' locations, what constitutes a valid attribute_name, or the implications of different cardinality values. The ctx parameter is noted as auto-injected but not explained.

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 states the action ('Add an attribute facet') and the target ('to a specification'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate this tool from its many siblings (like add_classification_facet, add_property_facet, etc.), which would require explaining what makes an 'attribute facet' distinct from other facet types.

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 alternatives. With 16 sibling tools including various 'add_*_facet' and 'add_*_restriction' tools, there's no indication of when an attribute facet is appropriate versus a classification facet, property facet, or any restriction type. The description also doesn't mention prerequisites or dependencies.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. It states what the tool does and shows a return format, but doesn't explain important behavioral aspects: whether this is a mutation operation, what permissions are needed, whether the restriction replaces existing ones, error handling, or side effects. The example helps but doesn't cover behavioral traits comprehensively.

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 reasonably structured with sections for Args, Returns, and Example. However, it includes redundant information (ctx parameter is auto-injected but listed) and could be more front-loaded. The example is helpful but the overall text could be more efficiently organized, with some sentences not earning their place in terms of clarity.

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 the tool's complexity (9 parameters, no annotations, schema coverage 0%), the description provides basic functionality explanation and parameter listing. The output schema exists (Returns section), so return values are documented. However, for a mutation tool with many parameters, it lacks crucial context about behavior, constraints, and integration with the broader system of sibling tools.

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?

With 0% schema description coverage, the description compensates well by listing all 9 parameters with brief explanations. It clarifies parameter meanings like 'facet_index: Index of facet in location (0-based)' and 'location: "applicability" or "requirements" (default: "requirements")'. The description adds significant value beyond the bare schema, though some parameter details remain unclear (e.g., how min_inclusive and min_exclusive interact).

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 states the tool's purpose: 'Add numeric bounds restriction' with an example showing it restricts values to a range. It distinguishes from siblings like 'add_enumeration_restriction' and 'add_pattern_restriction' by focusing on numeric bounds. However, it doesn't explicitly contrast with all sibling tools in the description text itself.

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 minimal usage guidance. The example mentions 'Add bounds to property value' which gives some context, but there's no explicit guidance on when to use this tool versus alternatives like 'add_enumeration_restriction' or 'add_length_restriction'. No prerequisites, error conditions, or when-not-to-use information is provided.

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?

With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states the action is 'Add' (implying mutation) and shows a return format, but doesn't disclose permissions needed, whether changes are reversible, error conditions, or side effects. For a mutation tool with zero annotation coverage, this is insufficient.

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 efficiently structured with a purpose statement followed by Args and Returns sections. Every sentence earns its place, though the 'ctx: FastMCP Context (auto-injected)' note could be omitted as it's implementation detail not needed for tool selection.

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 the mutation nature (no annotations), 5 parameters with 0% schema coverage, and presence of an output schema, the description does well by explaining all parameters and showing a return example. However, it lacks context about when this operation is valid or what happens on failure, leaving some gaps for a mutation tool.

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%, but the description compensates well by explaining all 5 parameters in the Args section with clear meanings (e.g., 'location: "applicability" or "requirements"', 'cardinality: "required", "optional", or "prohibited"'). It adds significant value beyond the bare schema, though it doesn't explain format details like what a 'specification identifier' entails.

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 states the specific action ('Add a classification facet') and target resource ('to a specification'), distinguishing it from sibling tools like add_attribute_facet or add_material_facet by specifying the facet type. The verb+resource combination is precise 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?

No guidance is provided on when to use this tool versus alternatives like add_entity_facet or add_property_facet. The description mentions the tool's function but doesn't indicate appropriate contexts, prerequisites, or exclusions relative to sibling tools.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully describes important constraints (the 'only ONE entity facet' rule), error conditions (raises ToolError for second entity in applicability), and the return format. However, it doesn't mention authentication needs, rate limits, or whether this is a read-only vs. write operation.

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 well-structured with clear sections (purpose, important constraint, args, returns, raises) and front-loads the most critical information. Every sentence earns its place, though the formatting could be slightly more compact. The information density is high with minimal 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 the complexity (mutation tool with constraints), 0% schema coverage, and the presence of an output schema, the description provides excellent completeness. It explains the tool's purpose, usage constraints, all parameters, return values, and error conditions. The output schema handles return format details, so the description appropriately focuses on operational 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?

With 0% schema description coverage, the description fully compensates by explaining all 5 parameters in detail: spec_id, location (with allowed values), entity_name (with example), predefined_type (optional), and cardinality (with allowed values and context restriction). It adds crucial meaning beyond the bare schema, including constraints like 'requirements only' for cardinality.

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 states the specific action ('Add an entity facet') and the target resource ('to a specification'), distinguishing it from sibling tools like add_attribute_facet or add_material_facet. It provides concrete details about what an entity facet is (IFC entity name) and its purpose within IDS specifications.

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 explicit guidance on when to use this tool vs alternatives: it states 'If you need multiple entity types, create separate specifications' and warns about the 'only ONE entity facet per applicability section' constraint. It also clarifies that cardinality is 'requirements only', helping the agent understand context-specific usage.

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?

With no annotations provided, the description carries the full burden. It discloses that this is a write operation ('Add'), implies it modifies specifications, and shows the return format. However, it doesn't mention permissions needed, whether changes are reversible, error conditions, or rate limits. The example helps but doesn't fully cover behavioral traits for a mutation tool.

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 well-structured and appropriately sized. It starts with a clear purpose statement, lists args with brief explanations, shows returns, and provides a concrete example. Every sentence earns its place, with no redundant information. The formatting (bullet-like args list) enhances 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?

Given 6 parameters with 0% schema coverage and no annotations, the description does a good job explaining most parameters and the tool's purpose. The output schema is provided via the Returns section, so return values are documented. However, for a mutation tool with complex parameters, it could benefit from more behavioral context (e.g., error handling, idempotency).

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 provides meaningful explanations for all parameters: 'spec_id' as 'Specification identifier or name', 'facet_index' as 'Index of facet in location (0-based)', etc. The example illustrates how 'parameter_name' and 'values' work. However, it doesn't explain 'ctx' (auto-injected) or provide format details for 'base_type' beyond examples.

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 states the tool's purpose: 'Add enumeration restriction (list of allowed values)' with a specific verb ('Add'), resource ('enumeration restriction'), and scope. It distinguishes from siblings like 'add_bounds_restriction' or 'add_pattern_restriction' by specifying the restriction type. The example further clarifies by showing it restricts property values to specific enumerated options.

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 clear context for when to use this tool: to add enumeration restrictions to parameters in specifications. It mentions the 'location' parameter defaulting to 'requirements', implying usage in that context. However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings (e.g., when to choose 'add_bounds_restriction' instead).

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?

With no annotations provided, the description carries full burden for behavioral disclosure. While it shows the return format and mentions the tool adds restrictions, it doesn't clarify whether this is a mutation operation, what permissions are needed, whether changes are reversible, or any rate limits. The example helps but doesn't cover behavioral traits adequately.

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 appropriately structured with clear sections (Args, Returns, Example) but contains some redundancy. The first sentence 'Add string length restriction.' is concise, but the example essentially restates the purpose. The parameter explanations are necessary given the poor schema coverage, making the overall length reasonable but not optimally efficient.

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 the complexity (8 parameters, 4 required), 0% schema coverage, and presence of an output schema, the description provides substantial parameter semantics and shows the return format. It covers what the tool does and how to use it, though behavioral aspects like mutation effects and prerequisites are missing. The output schema reduces the need to explain return values.

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?

With 0% schema description coverage, the description compensates well by explaining all 8 parameters in the Args section with clear meanings (e.g., 'spec_id: Specification identifier or name', 'location: "applicability" or "requirements"'). It provides examples for parameter_name and base_type, and clarifies the relationship between length/min_length/max_length parameters.

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 states the tool's purpose as 'Add string length restriction' and provides a concrete example about restricting tag length between 5 and 50 characters. However, it doesn't explicitly differentiate this from sibling tools like 'add_bounds_restriction' or 'add_pattern_restriction', which likely handle different types of restrictions.

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 alternatives like 'add_bounds_restriction' or 'add_pattern_restriction'. It mentions an example about restricting attribute values, but offers no explicit when/when-not instructions or prerequisites for usage.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. While it states this is an 'add' operation and shows a return format, it doesn't mention whether this operation is idempotent, what happens if the facet already exists, what permissions are required, or any side effects. For a mutation tool with zero annotation coverage, this leaves significant behavioral questions unanswered.

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 well-structured with clear sections (purpose, Args, Returns) and uses minimal sentences. The Args section efficiently documents all parameters without redundancy. The only minor improvement would be integrating the purpose statement more seamlessly rather than having it as a separate fragment.

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 the tool has 4 parameters, no annotations, and an output schema (implied by Returns section), the description covers the basic operation and parameters adequately. However, for a mutation tool that modifies specifications, it should ideally mention prerequisites, side effects, or error conditions. The presence of an output schema reduces the need to explain return values, but behavioral context remains light.

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?

With 0% schema description coverage, the description must compensate, and it does so effectively by explaining all 4 parameters in the Args section. It clarifies that 'location' can be 'applicability' or 'requirements', 'material_value' accepts various formats, and 'cardinality' has three specific values. The only missing parameter is 'ctx' which is noted as auto-injected.

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 states the specific action ('Add a material facet') and target resource ('to a specification'), distinguishing it from sibling tools like add_attribute_facet or add_property_facet. It precisely identifies what type of facet is being added, making the purpose unambiguous and differentiated.

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 alternatives like add_attribute_facet or add_classification_facet. It mentions the 'location' parameter values but doesn't explain the conceptual difference between 'applicability' and 'requirements' contexts or when to choose this tool over other facet-adding siblings.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the action is 'Add' (implying mutation) and shows a return format, but doesn't cover permissions, side effects, error conditions, or system constraints. The description adds minimal behavioral context beyond the basic operation.

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 appropriately sized with a clear purpose statement followed by parameter documentation and return example. Every sentence serves a purpose, though the parameter documentation could be more integrated with the main description rather than in a separate 'Args:' section.

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 with 0% schema coverage and no annotations, the description provides basic parameter examples and a return example (output schema exists). However, for a mutation tool with multiple parameters, it lacks sufficient context about the domain, error handling, and integration with sibling tools.

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 provides examples for 'location', 'relation', 'parent_entity', and 'cardinality', which adds meaning beyond the bare schema. However, it doesn't explain 'spec_id' or 'parent_predefined_type', leaving 2 of 6 parameters without semantic clarification.

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 states the action ('Add a partOf facet') and target resource ('to a specification'), which is specific and unambiguous. It distinguishes from siblings like 'add_attribute_facet' or 'add_entity_facet' by specifying the facet type. However, it doesn't explicitly contrast with all sibling tools in the list.

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 alternatives like other 'add_*_facet' tools or 'add_specification'. It lacks context about prerequisites, typical workflows, or scenarios where this specific facet type is appropriate.

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?

With no annotations provided, the description carries full burden. It discloses the tool adds restrictions (implying mutation) and shows the return format, but lacks details about permissions needed, whether changes are reversible, error conditions, or rate limits. The behavioral disclosure is adequate but not comprehensive.

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?

Perfectly structured and appropriately sized: purpose statement first, then organized Args section, Returns, and Example. Every sentence earns its place with zero waste, and information is front-loaded effectively.

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 the tool's complexity (6 parameters, mutation operation) and no annotations, the description does well with parameter explanations and includes output schema info. However, it could better explain the relationship between parameters (e.g., how facet_index relates to spec_id) and provide more behavioral context for a mutation tool.

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?

With 0% schema description coverage, the description compensates well by explaining all 6 parameters in the Args section with clear examples (e.g., 'parameter_name: Which parameter to restrict (e.g., "value")', 'location: "applicability" or "requirements"'). It adds substantial meaning beyond the bare schema, though some parameter relationships could be more explicit.

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 states the specific action ('Add pattern restriction') and resource ('regex matching'), distinguishing it from siblings like add_bounds_restriction or add_enumeration_restriction. The example further clarifies it's for restricting attribute values with regex patterns.

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 clear context about when to use this tool (adding regex pattern restrictions to specifications), and the example shows a specific use case. However, it doesn't explicitly state when NOT to use it or name alternatives among siblings like add_enumeration_restriction for non-regex constraints.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it's a mutation tool (implied by 'Add'), specifies that 'property_set' is required for valid export, documents the return format, and mentions error conditions ('Raises: ToolError'). It doesn't cover all potential behaviors like rate limits or auth needs, but provides substantial context beyond basic parameters.

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 well-structured with clear sections (purpose, important note, args, returns, raises) and front-loaded key information. Every sentence earns its place by providing essential details. It could be slightly more concise by integrating the 'IMPORTANT' note into the main description, but overall it's efficiently organized without wasted words.

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 the complexity (7 parameters, mutation operation, no annotations) and the presence of an output schema (implied by the 'Returns' section), the description is complete enough. It covers purpose, critical requirements, all parameter meanings, return values, and error conditions. The output schema existence means the description doesn't need to explain return values in detail, and it provides all necessary context for effective tool use.

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 fully compensate. It does so excellently by explaining all 7 parameters with clear semantics: 'spec_id' as specification identifier, 'location' with allowed values, 'property_name' with examples, 'property_set' as required for export with examples, 'data_type' as IFC type, 'value' as required value/pattern, and 'cardinality' with allowed values. This adds significant meaning beyond the bare schema.

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 states the tool's purpose with a specific verb ('Add') and resource ('property facet to a specification'). It distinguishes itself from siblings like 'add_attribute_facet' or 'add_material_facet' by specifying it's for property facets, not other types. The description explicitly mentions what it does rather than just restating the name.

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 some implied usage guidance by noting that 'property_set parameter is REQUIRED for valid IDS export,' which suggests when this tool is necessary for compliance. However, it doesn't explicitly state when to use this tool versus alternatives like 'add_attribute_facet' or other sibling tools, nor does it provide exclusions or prerequisites beyond the required parameter.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an 'Add' operation (implying mutation) and shows a return format, but doesn't address important behavioral aspects like: what happens if a specification with the same name already exists, whether this requires specific permissions, if changes are reversible, or any rate limits/constraints. The return example helps but doesn't constitute comprehensive behavioral transparency.

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 well-structured with clear sections (purpose, args, returns) and front-loads the core functionality. Every sentence adds value, though the parameter documentation is quite detailed (which is necessary given the 0% schema coverage). The structure helps the agent quickly parse the information, though it could be slightly more concise in the parameter explanations.

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 the tool's complexity (7 parameters, mutation operation, no annotations) and the existence of an output schema (implied by the return example), the description does a good job of providing necessary context. The parameter documentation is comprehensive, the return format is shown, and the purpose is clear. The main gap is lack of behavioral context and sibling differentiation, but overall it provides substantial guidance for correct tool invocation.

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?

With 0% schema description coverage, the description provides excellent parameter semantics compensation. It clearly documents all 7 parameters with meaningful explanations beyond just names: clarifying 'ifc_versions' format with examples, explaining optional vs required parameters, defining special values like 'unbounded' for max_occurs, and providing context for what each parameter represents in the domain (e.g., 'Why this information is required' for description).

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 states the action ('Add a specification') and target resource ('to the current session's IDS document'), providing a specific verb+resource combination. However, it doesn't differentiate this tool from its many siblings (like add_attribute_facet, add_bounds_restriction, etc.) which all seem to add different components to IDS documents, leaving the specific role of 'specification' versus other facet/restriction types unclear.

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 the 15 other sibling tools listed, nor does it mention prerequisites, dependencies, or alternative approaches. While it mentions the tool operates on 'the current session's IDS document,' this is more context than usage guidance, leaving the agent with no help in tool selection decisions.

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?

With no annotations provided, the description carries the full burden and does well by disclosing key behaviors: it creates a new document (implying a write/mutation operation), automatically tracks sessions (no session_id needed), and returns a specific JSON structure. It could improve by mentioning permissions, error cases, or rate limits, but covers essential operational context.

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 well-structured with a purpose statement, behavioral note, parameter details, and return format. It's appropriately sized but could be slightly more concise by integrating the 'Args' and 'Returns' labels into the flow. Every sentence adds value, with no wasted text.

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 the complexity (8 parameters, 1 required), no annotations, and an output schema provided, the description is complete. It explains the tool's purpose, usage context, parameters, and return values, covering all necessary aspects for an AI agent to invoke it correctly without relying on structured fields.

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 has 0% description coverage, but the description compensates fully by listing all 8 parameters in the 'Args' section with clear explanations (e.g., 'title: Document title (required)', 'date: Date in YYYY-MM-DD format'). It also notes that 'ctx' is auto-injected and 'title' is required, adding crucial meaning beyond the bare schema.

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 states the tool 'creates a new IDS document for this session' with a specific verb ('create') and resource ('IDS document'), and mentions session tracking. However, it doesn't differentiate from sibling tools like 'add_specification' or 'load_ids', which might also involve IDS document operations.

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 implies usage by stating 'for this session' and that 'Session is automatically tracked by FastMCP', suggesting it's for creating new documents within a tracked context. However, it doesn't explicitly state when to use this versus alternatives like 'load_ids' (for existing documents) or 'add_specification' (for modifying documents), leaving some ambiguity.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool automatically uses the current session (no session_id needed), can output to a file or return XML string, and includes validation capabilities. It also clearly explains the conditional return structure based on whether output_path is provided. The only minor gap is lack of information about error handling or performance characteristics.

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 perfectly structured and concise. It begins with the core purpose, then provides important usage note, followed by clear parameter documentation, and finally the return structure. Every sentence earns its place with no wasted words, and information is front-loaded appropriately.

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 the tool's moderate complexity (2 parameters, validation functionality), no annotations, and the presence of an output schema, the description is complete. It explains the tool's purpose, usage context, parameter behaviors, and the output schema handles return values. The description provides everything needed beyond the structured fields.

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 description coverage is 0%, so the description must fully compensate. It provides excellent parameter semantics: explains that 'ctx' is auto-injected (not a user parameter), describes 'output_path' as optional with clear behavior when omitted (returns XML string), and explains 'validate' with its default and purpose (validate against XSD). This adds substantial value beyond the bare schema.

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 states the tool's purpose: 'Export IDS document to XML file using IfcTester.' It specifies the verb (export), resource (IDS document), format (XML file), and technology (IfcTester). This distinguishes it from sibling tools like 'validate_ids' or 'create_ids' which have different functions.

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 clear context for usage: 'Uses current session automatically - no session_id parameter needed!' This indicates when to use this tool (with an active session) versus alternatives that might require session management. However, it doesn't explicitly state when NOT to use it or name specific alternative tools for different scenarios.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about automatic session usage and the return structure, but doesn't cover aspects like whether this is a read-only operation, potential errors, or performance considerations. The description doesn't contradict annotations (since none exist), but it provides only moderate behavioral insight beyond basic functionality.

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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by a key behavioral note, and then structured details on args and returns. Every sentence earns its place without redundancy, making it highly concise and well-structured for quick understanding.

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 the tool has 0 parameters, 100% schema coverage, and an output schema (implied by the Returns section), the description is reasonably complete. It explains the purpose, session usage, and return format, which covers the essentials. However, it could be more complete by addressing how it relates to sibling tools or potential error cases, but the output schema reduces the need for detailed return value explanations.

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 input schema has 0 parameters with 100% coverage, so the schema fully documents the lack of parameters. The description adds value by explicitly stating 'no session_id parameter needed!' and noting that 'ctx' is auto-injected, which clarifies parameter semantics beyond the empty schema. This compensates well for the simple parameter case.

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 states the tool's purpose: 'Get current session's IDS document structure.' It specifies the verb ('Get') and resource ('IDS document structure'), and clarifies it uses the current session automatically. However, it doesn't explicitly differentiate from sibling tools like 'load_ids' or 'create_ids', which might also involve IDS document operations.

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 some usage context by noting 'Uses current session automatically - no session_id parameter needed!', which implies when to use this tool (for current session) versus alternatives that might require session parameters. However, it doesn't explicitly state when to use this tool over siblings like 'load_ids' or 'export_ids', leaving usage somewhat implied rather than fully guided.

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?

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it 'Replaces any existing IDS in this session' (destructive effect), specifies the return structure, and mentions auto-injection of 'ctx'. It does not cover rate limits or auth needs, but provides sufficient operational context.

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 front-loaded with the core purpose, followed by behavioral note, parameter details, and return values in a structured format. Every sentence adds value with no redundancy, making it efficient and easy to parse.

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 the tool's complexity (loading files with session state impact), no annotations, and an output schema that documents return values, the description is complete. It covers purpose, behavior, parameters, and output, leaving no gaps for the agent to operate correctly.

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 fully. It effectively explains both parameters: 'source' as 'File path or XML string' and 'source_type' as '"file" or "string"', adding crucial meaning beyond the bare schema. This covers all parameters comprehensively.

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 states the verb 'Load' and resource 'IDS file' into 'current session', distinguishing it from sibling tools like 'create_ids', 'export_ids', or 'get_ids_info'. It specifies the action is about loading existing files rather than creating new ones or exporting.

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 clear context for when to use this tool: to load an IDS file into a session. It implicitly distinguishes from alternatives like 'create_ids' for new files or 'validate_ids' for checking, but does not explicitly state when not to use it or name specific 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?

With no annotations provided, the description carries full burden and does well by detailing what gets validated (four specific checks) and the return structure. It doesn't mention performance characteristics, error handling, or prerequisites like needing a loaded IDS document first, but covers core behavior adequately for a validation tool.

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 efficiently structured with a clear purpose statement, bulleted validation criteria, and explicit return format. Every sentence adds value: the first states what's validated, the bullets detail criteria, and the return section explains output. No wasted words or redundancy.

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 the tool has 0 parameters, no annotations, but a detailed output schema in the description, the description is complete. It explains what validation entails, documents the return structure thoroughly, and provides enough context for an agent to understand when and how to use this tool effectively.

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 input schema has 0 parameters with 100% coverage, so the baseline is 4. The description appropriately notes that 'ctx: FastMCP Context' is auto-injected, adding useful context about parameter handling without needing to document non-existent user parameters.

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 states the specific action ('validate') and target resource ('current session's IDS document'), distinguishing it from sibling tools like 'validate_ifc_model' which validates a different resource. It provides concrete validation criteria (required fields, applicability, IFC versions, XSD compliance) that make the purpose unambiguous and distinct.

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 implies usage context by specifying it validates 'current session's IDS document', suggesting it should be used when an IDS document is loaded in the session. However, it doesn't explicitly state when not to use it or name alternatives like 'validate_ifc_model' for different validation scenarios, leaving some guidance gaps.

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. It discloses that this is a validation tool (implying read-only behavior) and mentions it's a 'bonus feature,' which adds some context. However, it lacks details on permissions, rate limits, error handling, or whether it modifies the IFC file, leaving behavioral traits partially covered but incomplete.

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 appropriately sized and front-loaded with the core purpose in the first sentence. The additional details on args and returns are structured but slightly verbose; however, every sentence adds value (e.g., explaining IfcTester and return format), with minimal 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 the complexity of validation with 2 parameters and no annotations, the description is complete enough. It includes purpose, parameter semantics, and a detailed return format in the output schema, which eliminates the need to explain return values. This covers essential context for the agent to invoke the tool correctly.

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 meaning by explaining 'ifc_file_path' as the path to the IFC file and 'report_format' with specific enum values ('console', 'json', 'html'), including a default of 'json' in the schema. This provides clear semantics beyond the bare schema, though it could elaborate on path format or context usage.

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 states the tool's purpose with a specific verb ('validate') and resource ('IFC model'), and distinguishes it from siblings by specifying it validates against IDS specifications. It explicitly mentions leveraging IfcTester's capabilities, which further clarifies its unique function compared to other tools like 'validate_ids' or 'create_ids'.

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 implies usage context by stating it validates 'against the current session's IDS specifications,' suggesting it should be used after IDS specifications are loaded or created. However, it does not explicitly state when to use this tool versus alternatives like 'validate_ids' or provide any exclusions or prerequisites, leaving some ambiguity for the agent.

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