Server Quality Checklist

Tool Scores

• delete_conceptA
  3.7/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It explicitly discloses that links to the concept from other concepts' causes are scrubbed, which is a significant side effect. However, it does not mention irreversibility, required permissions, or return value, leaving some gaps in transparency.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences, directly front-loaded with the main action, and every sentence contributes meaningful information. It is appropriately sized and avoids unnecessary detail.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has one parameter, no annotations, and no output schema. The description covers the core action and the link-scrubbing side effect, but it lacks information about permanence, return value, or error conditions, which are relevant for a delete operation. For its simplicity, it is reasonably complete but not fully specified.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema has a single 'id' parameter with no description, and the description only says 'by id,' which aligns with the parameter name but adds little extra meaning. It does not specify the id format or clarify that it is the concept's unique identifier beyond what the property name implies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool deletes a concept by id, with a specific verb and resource. It also distinguishes itself from sibling tools like get_concept and upsert_concept by focusing on deletion, and the added detail about scrubbing links clarifies the operation.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  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, such as upsert_concept, or when not to use it. There are no prerequisites, exclusions, or references to other tools, leaving the usage context entirely implicit.

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

• list_coverage_gapsA
  3.9/5.0
  Behavior3/5

  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 explaining behavior. It clearly indicates this is a listing operation (no side effects implied) and adds semantic context about candidates and usage ranking. However, it does not disclose details like return format, whether results are ordered, or any permissions needed. The description is adequate but lacks rich behavioral disclosure.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences long, front-loaded with the core definition, and ends with actionable usage guidance. Every word earns its place, with no redundancy or filler. It is a model of concise, structured communication.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no output schema and no annotations, the description covers the main contextual needs: purpose, use case, and ranking strategy. It could be more complete by describing the output structure or default behavior, but the combination of the purpose statement and usage guidance provides a solid understanding for agent selection. The clarity of the tool's place in the workflow compensates for minor omissions.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already documents 'limit' and 'offset' with descriptions, but the 'kind' parameter has no description. The tool description adds no parameter-specific meaning and does not mention that you can filter by entity type. While the enum values are self-explanatory, the description misses the opportunity to clarify the role of 'kind' in the context of coverage gaps, leaving the parameter semantics under-specified.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states it lists 'Entities NOT measured by any concept' and frames them as 'candidates for new business definitions.' This specific verb-resource pairing distinguishes it from sibling tools like get_concept or lookup_ontology, which handle existing concepts or maps. The purpose is immediately clear and non-tautological.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit guidance on how to use the results: 'Join with usage data from the Pendo MCP server (e.g. entityUsage) to rank' and identifies high-usage unmeasured entities as strongest candidates. This gives a clear use case and workflow, though it does not name alternatives or explicitly say when not to use this tool. Still, the context is strong enough for an agent to decide appropriately.

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

• upsert_conceptA
  4.2/5.0
  Behavior3/5

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

  With no annotations provided, the description must disclose behavior itself. It does explain autoLink behavior and frames the tool as an ontology write, but it does not mention update side effects, reversibility, permissions, or return shape. This is moderate transparency 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three sentences, front-loaded with the core action, and includes a helpful example and usage rationale without irrelevant details. Every sentence contributes value.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  This is a complex 10-parameter upsert with no output schema or annotations. The description manages the complexity well by outlining the concept structure and autoLink behavior, but it omits details about the response, update semantics beyond the schema, and potential merging behavior. Still, it is reasonably complete for an agent to decide when and how to invoke it.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is about 50%, and the description adds meaningful context by linking measures, causes, and actions to the concept's overall purpose. It also clarifies that autoLink=true attaches deterministic name-matched entities. However, some parameters like tags, source, and measurementHint remain underspecified.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb phrase — 'Create or update a business concept' — and clearly identifies the resource and its purpose: a named definition linked to measured entities, causes, and playbook actions. This distinguishes it from siblings like get_concept and delete_concept.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description states a clear usage context: 'This is how meaning gets INTO the ontology — prefer enriching it whenever the user defines or clarifies a business term.' It gives explicit when-to-use guidance, though it does not name specific alternatives or exclusions.

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

• ingest_pendo_payloadA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden. It discloses normalization and merging behavior, explains how default kind is applied and overridden by per-item evidence. Missing details on merge semantics (e.g., overwrite vs. append) but the core behavior is well described.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but focused. It front-loads the main idea and uses examples to clarify. The phrase 'EASIEST' is slightly promotional but the content is informative without being bloated.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with no output schema and no annotations, the description covers input formats, parameter behavior, and merge logic well. It does not describe return values or error handling, but the primary ingest purpose is adequately addressed.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, but the description adds meaningful context: explains that `kind` is a default for items lacking kind evidence, `payload` can be array/wrapper/JSON string, and `appId` is stamped. This goes beyond the schema's static descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: ingest raw Pendo MCP tool results and normalize/merge them into the ontology. It enumerates specific source tools and input formats, and the distinction from siblings like 'sync_from_pendo' is implicit by focusing on raw payload ingestion.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides explicit usage context: pass raw Pendo MCP results, and indicates when `kind` is required (for product areas and segments). It does not explicitly contrast with alternative tools like sync_from_pendo, but the examples and instructions give clear practical guidance.

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

• register_entitiesA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full transparency burden. It adds valuable behavior beyond the schema by explaining the ID derivation rule ("<kind>:<pendoId>") and its stability, which reassures about re-registration. It does not mention the destructive impact of `replace` mode, but that is already covered in the schema's parameter description, so the description still adds meaningful new information.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three sentences that are all front-loaded and purposeful: first the main action, then the explicit alternative, then a key behavioral detail. There is no fluff or repetition of schema content.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has moderate complexity (two parameters, one nested array) and no output schema, so the description should provide some sense of return values or broader side effects. It covers purpose, usage guidance, and ID stability, but it does not hint at what the tool returns or the full consequence of `replace` mode (replacing the entire structural layer). Since the schema already covers the mode behavior, this is a moderate gap, not a fatal one.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is only 50%, so the description should compensate. It partially does by clarifying how `pendoId` and `kind` are used to form stable IDs, adding semantic meaning to those fields. However, it does not elaborate on the `mode` parameter or other entity fields beyond what the schema already states, so compensation is incomplete.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's action ('Register or update') and its resource ('Pendo entities in the structural layer') with a specific method ('using an explicit, pre-shaped list'). It also distinguishes itself from sibling tools, especially `ingest_pendo_payload`, by contrasting raw results with pre-shaped lists.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly provides an alternative tool ('prefer ingest_pendo_payload') and the condition for using it ('For raw Pendo MCP tool results'), giving clear when-to-use and when-not-to-use guidance. This is directly useful for agent selection.

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

• get_entity_catalogueA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses that the catalogue is filterable and paginated, and that it returns features grouped by product area. It also warns against paging through everything. However, it does not explicitly state that the operation is read-only or describe the response shape, so a small gap remains.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences long, front-loads the core definition, and provides actionable guidance without fluff. Every word earns its place, including the parenthetical emphasis on mapping by meaning.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read-only listing tool with 5 optional parameters and no output schema, the description provides sufficient context: purpose, filters, pagination, and usage strategy. It does not describe the exact return fields, but that is not strictly necessary for tool selection and invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so baseline is 3. The description adds strategic advice about preferring search/kind filters but does not explain individual parameters beyond what the schema already provides. It adds some context about entities being features grouped by product area, but not enough to raise the score.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool returns a catalogue of registered entities grouped by product area, with filtering and pagination. It also specifies a concrete use case (picking entity IDs when linking concepts to measured meanings), which distinguishes it from sibling tools like lookup_ontology or get_concept.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicit guidance is provided: 'Use this to pick entity ids when linking a concept to what it measures' and 'Prefer search/kind filters over paging through everything.' This tells the agent when to use the tool and the appropriate strategy, fulfilling the dimension well.

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

• lookup_ontologyA
  4.4/5.0
  Behavior4/5

  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 significant behavioral detail: case-insensitive substring matching and distinct return payloads for entity, productArea, and concept hits. It does not cover error handling or side effects, but this appears to be a read-only search.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single well-structured sentence that front-loads the primary action and efficiently describes conditional return behaviors. Every clause adds necessary information without redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given 3 parameters and no output schema, the description provides a solid map of the response space, covering the main return variants and their fields. It omits ordering/pagination details, but the limit parameter's schema covers max results, so overall completeness is adequate.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already describes all 3 parameters, but the description adds semantic value: it explains the query interpretation (case-insensitive substring) and how the kind of the matched item changes the response structure. This supplements the schema description of the 'query' parameter.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action ('Search the ontology by name') and specifies matching mode (case-insensitive substring). It distinguishes this tool from siblings like get_concept or list_coverage_gaps by describing different result types (entity, productArea, concept) and what each returns.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies when to use the tool: when searching ontology entries by name and expecting polymorphic results. It doesn't explicitly name alternatives or provide exclusions, but the context makes the primary use case clear.

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

• suggest_linksA
  4.4/5.0
  Behavior4/5

  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 key behavioral traits: 'Deterministic' and 'precision FLOOR,' which sets expectations for output quality/scope. It also notes the limitation (string matching only) and directs the model to supplement with another tool. However, it does not specify the exact return format or potential errors, so a small gap remains.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences, no fluff. The first sentence delivers the core purpose immediately; the second provides essential guidance. Every sentence earns its place, and the structure is easy to parse.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple single-parameter tool with no output schema, the description covers purpose, usage, and even a cross-reference to a sibling tool. It does not specify the return format (e.g., entity IDs), but given the tool's simplicity and the strong usage guidance, it is nearly complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% and the single parameter already has a description in the schema ('Concept name and/or definition (the problem statement).'). The tool description adds no new parameter details beyond referencing 'the given statement,' which is consistent with the schema. Thus baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states exactly what the tool does: 'Deterministic candidates for what a concept measures: entities whose names phrase-match the given statement.' It uses a specific verb ('suggest') and resource ('links' as entities), and distinguishes itself from get_entity_catalogue by emphasizing deterministic phrase matching.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly instructs the model to 'additionally pick semantically related entities from get_entity_catalogue that string matching cannot find,' defining when to use this tool (for string matches) and when to use the alternative. This is clear and actionable guidance.

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

• sync_from_pendoA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses a critical safety behavior: 'Merges by stable id — concepts are never touched,' which is essential context. It also mentions the environment variable prerequisite. However, it doesn't detail side effects like whether existing data is overwritten or what happens on failure, though the key safety guarantee is covered.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is only two sentences with the main action first, followed by a prerequisite and a safety note. Every phrase earns its place, and there is no fluff or repetition.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with only two optional parameters and no output schema, the description covers the core aspects: the action, prerequisite, alternative, and a safety guarantee. It doesn't mention the return value or error modes, but these are not critical for a simple sync tool, and the overall context is sufficient.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Both parameters (appId and expandAll) have full descriptions in the schema, covering their purpose and scoping behavior. The tool description adds no additional parameter-specific meaning beyond the schema, so it meets the baseline for high schema coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool syncs features, pages, segments, and product areas from the Pendo REST API, using the specific verb 'sync' and resource list. It also distinguishes itself from register_entities by naming it as an alternative, making its unique purpose obvious.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It explicitly states when to use the tool (requires PENDO_INTEGRATION_KEY) and when not to ('without it, use register_entities'), providing a clear alternative. The 'OPTIONAL' prefix further clarifies its non-required status.

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

• get_conceptA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses case-insensitive name matching and the scope of returned data, and implies read-only behavior with 'get'. It does not mention behavior for unknown IDs or not-found cases, but for a single-concept getter 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences: the first front-loads the action, target, and return fields; the second gives usage context. No wasted words or repetition of schema details.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple read tool with two optional parameters and no output schema, the description adequately covers what the tool returns, how to identify the target concept, and when to use it. The absence of an error-handling note is minor given the tool's straightforward nature.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already provides full descriptions for both parameters, including case-insensitivity and first-match-wins behavior. The description only paraphrases the id-or-name distinction without adding new meaning, so it meets the baseline for high schema coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool retrieves full detail for exactly one concept by id or name, listing the included fields (definition, measurement hint, measured entities with pendoIds, causes, playbook actions). This distinguishes it from sibling tools like get_product_map which focuses on map-level identification.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly instructs to use this tool after get_product_map has identified the relevant concept, providing clear sequencing and implicit differentiation from alternatives like lookup_ontology or list_coverage_gaps.

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

• get_product_mapA
  4.9/5.0
  Behavior5/5

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

  No annotations provided, so the description carries the full burden. It discloses the default return format ('concept BRIEFS by default (name, truncated definition, tags, link counts)'), the effect of detail:'full' ('expands in place, paginated'), and adds a performance caution ('use sparingly'). It also notes the output is paginated, a behavioral trait not in the schema. This is transparent for a read tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three concise sentences, each serving a distinct purpose: purpose, usage guidance, and output/parameter detail. No filler or redundant repetition of schema information. Front-loaded with the core purpose.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  No output schema exists, so the description appropriately explains the return payload (briefs, full detail) and pagination. It also provides the essential usage context (workspace vocabulary, first call) and the alternative for full detail. Given the tool's moderate complexity (3 simple params), the description is complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Input schema covers all three parameters with descriptions (100% coverage), establishing a baseline of 3. The description adds value by clarifying the default behavior ('Returns concept BRIEFS by default') and by giving additional guidance on the detail parameter ('use sparingly', 'expands in place') – context not present in the schema description alone. This raises the score to 4.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States it provides an 'Overview of the workspace ontology: entity counts and the concept index' – a clear resource and scope. It explicitly positions itself as the entry point ('Call this FIRST') and differentiates from get_concept by directing full-detail lookups there. This distinguishes it from sibling tools by its role as the top-level index.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly says 'Call this FIRST when answering product-analytics questions' – clear when to use. Names get_concept as the alternative for full detail on a single concept, and cautions 'detail:"full" expands in place (paginated; use sparingly)' – telling when to avoid using the full mode. This is ideal usage guidance.

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