Senzing

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

The description discloses key behaviors: the tool returns a Python script with instructions, no source data is sent to the server, and it validates records and examines data quality. This adds significant context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint).

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 concise and well-structured: it starts with the tool's purpose, then details requirements, functionality, and workspace_dir specifics. Every sentence adds value, with no redundancy or 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 tool has 3 parameters, no output schema, and no nested objects, the description fully covers what the agent needs: it explains the return type, prerequisites, behavior, and provides examples. The annotations and schema complement this well, making the definition complete.

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 description adds substantial meaning beyond the input schema, especially for 'workspace_dir' by explaining its criticality, typical values, and environment-specific considerations. The schema already covers 100% of parameters, but the description provides practical guidance that enhances agent understanding.

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 returns a Senzing JSON analyzer script for client-side validation. It specifies the verb 'Get' and the resource 'analyzer script', making the purpose distinct from sibling tools which cover different functionalities like downloading or searching.

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 prerequisites, notably the 'workspace_dir' requirement and typical values. However, it does not explicitly compare to alternative tools or state when not to use this tool, which would elevate the score to 5.

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?

Beyond annotations (readOnly, idempotent), description adds details: returns list if no params, asset IDs unstable, mode differences (HTTP vs stdio), inline token consumption warning. No contradiction.

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?

Well-structured and front-loaded with purpose. A few extra sentences on available resources could be separate but are helpful. Not overly verbose.

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?

No output schema, but description explains return types (URLs, commands, inline) and behavior with no parameters. Also warns about token cost and version instability. Fully complete for a download 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 covers all parameters with descriptions. The description adds crucial usage context (inline=false first, filename/filenames precedence, version defaults), exceeding schema alone.

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 downloads resources by name, lists available resources, and explains behavior when no filename is provided. It distinguishes itself from siblings which focus on analysis, not downloading.

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?

Provides clear guidance on filename vs filenames precedence and inline parameter usage. Lacks explicit when-not-to-use instructions but siblings are distinct, so this is minor.

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?

Annotations already declare readOnly and idempotent. Description adds accepted input formats and output details (error class, causes, resolution), which is valuable beyond annotations.

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

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

Two sentences, front-loaded with purpose, efficient and to the point.

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?

Covers purpose, input formats, and output content. Missing prerequisites or existence checks, but sufficient for a simple lookup tool with good annotations.

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 has 0% coverage; description explains error_code format but not version parameter. Adequate compensation for the main parameter but ignores optional one.

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?

Clearly states the tool explains Senzing error codes with causes and resolution steps. Distinguishes itself from sibling tools like analyze_record or search_docs.

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?

Indicates when to use: to explain an error code. No explicit exclusions or alternatives, but context is straightforward for a lookup tool.

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?

Annotations already declare read-only, idempotent, non-destructive. Description adds indexed file types, excluded files, three modes, max_lines behavior, and output format (GitHub raw URLs), providing full behavioral 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?

Description is long but well-structured: first paragraph gives critical requirements and modes, second paragraph details content and capabilities. Every sentence adds value, no 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 complexity (6 params, 3 modes, no output schema), description is thorough: covers modes, parameter combos, indexed content, output format, and limitations (max_lines, excluded files).

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 coverage is 100%, baseline 3. Description adds value by linking parameters to modes, clarifying query requirement, and explaining max_lines purpose, going beyond schema details.

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?

Description clearly states the tool finds working source code examples from 37 indexed repos, specifying the resource and action. It distinguishes from siblings like get_sample_data and search_docs.

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

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

Explicitly describes three modes with required parameter combinations and warns of failure without proper setup. Mentions alternative get_sample_data for data files, but lacks when-not-to-use for other 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?

Discloses that the tool returns URLs to fetch, not the code itself, and mentions indexing and provenance. Annotations already cover safety (readOnlyHint, idempotentHint), so description adds useful behavioral context beyond structured data.

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 about 5 sentences, front-loaded with purpose and usage guidance. It is informative without being verbose, though could be slightly more concise by grouping details.

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 (3 parameters, no output schema), the description fully explains the return format (URLs to fetch), supported values, and aliases. No gaps for agent to infer.

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 coverage is 100%, but description adds significant value: list of languages with aliases, workflows with aliases, and version constraints (V3 supports Python and Java only). This exceeds minimal schema documentation.

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 states a specific verb ('Generate') and resource ('SDK scaffold code'), clearly distinguishing it from sibling tools like analyze_record or search_docs. It explicitly mentions the source (GitHub) and provenance.

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

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

Explicitly advises using this tool INSTEAD of hand-coding SDK calls, citing common errors. Lists supported languages and workflows with aliases, providing clear when-to-use guidance.

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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description discloses that it returns server_info with name, version, Senzing version, and a manifest of coverage areas. It also warns about risks of skipping, adding valuable context not present in annotations.

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

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

The description is thorough and front-loaded with purpose, but is slightly verbose. However, every sentence adds value, and the structure is logical, moving from purpose to usage guidance to return content.

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

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

While the description covers return content and usage context, it omits explanation of the 'version' parameter, which is the only input. Given no output schema, the description should fully define the input's role to be complete. This gap reduces completeness.

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 an optional 'version' parameter with default 'current', but the description does not explain its purpose or behavior. With 0% schema coverage, the description should compensate but fails to clarify how this parameter affects the output, leaving agents without guidance.

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 specifies the tool's purpose: retrieving server version, capabilities overview, available tools, suggested workflows, and getting started guidance. It uses specific nouns and distinguishes itself from sibling tools by positioning itself as the first triage tool.

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: 'Call this first when working with Senzing entity resolution... skipping this risks using wrong API method names...' It also advises using it to triage before external sources, effectively telling the agent when to use this tool.

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?

Annotations already state readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds important behavioral context: data is real (not synthetic), historical snapshots for evaluation only, not for operational use, and asset IDs are not stable. No contradictions with annotations.

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

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

Description is well-structured with clear sections and front-loaded main purpose. Each sentence adds value, though it is slightly lengthy. Could be trimmed but overall effective.

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?

No output schema exists, but description explains the preview nature of returned records and the download_url behavior in different modes (HTTP vs stdio). It also warns about asset ID instability and provides instructions for when extraction fails. This is complete for the tool's purpose.

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 coverage is 75% (limit lacks description). The description adds meaning by explaining that dataset='list' discovers datasets, source='list' shows vendors, and offset can be 'random'. This goes beyond schema definitions.

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 states 'Get real sample data from CORD datasets' which is a specific verb+resource. It distinguishes itself from siblings like analyze_record or download_resource by focusing on retrieving sample data and includes special features like listing datasets/sources.

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?

Explicit instructions are given for discovering available datasets (dataset='list') and sources (source='list'). It also provides critical usage guidance (inform user data is real, do not download yourself, present fetch instructions). However, it does not explicitly mention when not to use this tool vs 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?

Annotations cover safety (readOnly/idempotent), so description appropriately focuses on content behavior: explains 'authoritative' data types and details what each topic returns (breaking changes, flag mappings, JSON schemas). No contradictions with annotations.

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

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

Four dense sentences with zero waste: purpose statement → sibling differentiation → topic enumeration with parenthetical explanations → filter usage. Front-loaded with clear intent; enumeration is necessary given string-type parameter without strict enum constraints.

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?

No output schema exists, but description compensates by detailing return content for each topic. With 100% schema coverage and comprehensive annotations, the description successfully rounds out the specification by explaining topic-specific return structures.

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?

While schema has 100% coverage, description adds critical enumerations and semantics: lists all valid topic values ('functions', 'methods', 'classes', 'api' in addition to schema's basic list) and explains what data each returns. Clarifies filter parameter usage patterns with specific examples (method name, module name).

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?

Excellent specific purpose: 'Get authoritative Senzing SDK reference data for flags, migration, and API details.' Clearly identifies resource (SDK reference) and scope. Explicitly distinguishes from sibling tool search_docs, preventing confusion.

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?

Explicit directive: 'Use this instead of search_docs when you need precise SDK method signatures...' provides clear when-to-use vs alternative. Topic enumeration further guides selection (use 'migration' for V3→V4 changes, 'flags' for engine flags, etc.).

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?

Description contradicts annotations: annotations state readOnlyHint=true, but description describes file creation (scripts, reference docs, mapper code, outputs saved to workspace_dir), implying mutation. This is a serious inconsistency.

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?

Description is well-structured with sections (actions, required params, state, common errors) and front-loads core purpose. However, it is verbose and could be more concise; every sentence adds value but the length could be trimmed.

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

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

Given the complexity of the 8-step workflow and detailed schema, the description covers all necessary aspects: actions, state management, required parameters, common errors, and reasons to use this tool. It is complete for an AI agent to invoke 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 coverage is 100%, baseline 3. Description adds practical guidance beyond schema: explains required params for start (file_paths, workspace_dir), imperative that state be passed verbatim, and covers common errors. This enhances usability.

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 'Map source data to Senzing JSON through a guided 8-step workflow' and specifies it should be used instead of hand-coding, providing a specific verb and resource.

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

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

Explicitly says 'Use this INSTEAD of hand-coding Senzing JSON' and explains why hand-coding is error-prone. Also provides context for when to use start vs other actions and warns about common errors.

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?

Annotations confirm read-only safety (readOnlyHint=true, destructiveHint=false), so the description appropriately focuses on content behavior rather than safety. It adds valuable behavioral detail: the conditional return of 'decision trees' when optional parameters are omitted, and explicitly lists the 8 topic domains covered, preventing surprise about the breadth of guidance provided.

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?

Four dense sentences with zero waste: sentence 1 establishes scope, sentence 2 lists cross-language capabilities and artifacts, sentence 3 maps the topic parameter to specific content types, and sentence 4 explains conditional behavior. Every clause delivers actionable information about tool capabilities.

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 (covering 8 distinct technical domains from SQL analytics to network graphs) and lack of output schema, the description adequately previews return content types (patterns, queries, schemas, anti-patterns) and conditional behaviors. A minor gap is the lack of explicit output format indication (text vs structured), though the content descriptions imply text/documentation.

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 100% schema coverage, the baseline is 3, but the description elevates this by explaining the semantic consequence of omitting 'language' and 'scale' parameters (triggers decision tree responses). It also implicitly validates the 'topic' enum by listing all 8 valid values with their semantic meanings in parentheses.

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

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

The description opens with the specific scope ('Guided reporting and visualization for Senzing entity resolution results') and enumerates distinct deliverables (SDK patterns, SQL queries, data mart schemas, visualization concepts). This clearly distinguishes it from siblings like sdk_guide (general SDK usage) or mapping_workflow by focusing specifically on reporting output and analytics.

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 what the tool delivers (guidance on 8 specific topics from export to evaluation) and hints at the interactive selection pattern ('Returns decision trees when language/scale not specified'). While it doesn't explicitly name sibling tools to avoid, the scope is distinct enough that the agent can infer appropriate 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond annotations: 'Returns real, compilable code snippets extracted from official GitHub repositories with source attribution,' and details the package URL behavior in HTTP vs. stdio modes. It also warns that 'Asset IDs are not stable across versions.' No contradiction with annotations.

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

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

The description is fairly long and contains many details. While all sentences are relevant, the structure could be improved (e.g., bullet points for modes, topics). It is front-loaded with the core purpose but becomes dense with specifics. It is appropriately sized for the complexity but leans toward verbose.

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, many topics, and platform/language variations, the description covers essential contextual details: HTTP vs. stdio mode, direct_download field, record_count thresholds, asset ID instability, and redirect to reporting_guide. No output schema exists, but the description compensates by explaining return features (direct_download, url). The description appears sufficient for an agent to use 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 100%, so each parameter has a baseline description. The tool description adds significant meaning: for record_count, it explains the threshold for production vs. demo patterns and license guidance; for topic, it lists all valid topics (matching schema but reinforcing); for language and platform, it notes that omitting returns a decision tree. This additional context helps an agent select appropriate values.

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 defines the tool's purpose: 'Install Senzing and scaffold SDK code across 5 platforms and 5 languages.' It specifies the verb (install/scaffold), resource (Senzing SDK code), and scope (platforms/languages). The title 'SDK Setup Guide' aligns and the description distinguishes from sibling tools by stating 'prefer this over hand-coding install commands or engine configuration.'

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 when-to-use guidance, such as 'prefer this over hand-coding install commands or engine configuration.' It also explains context-specific behavior: 'For load/search/redo, pass record_count to control template selection' and 'Export redirects to reporting_guide.' It gives alternative actions: 'If a previously-known ID fails to extract, call this tool again to obtain the current ID.' While clear, it does not explicitly cover when not to use (e.g., for simple queries where search_docs might be more 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?

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds that it returns ranked results with excerpts and supports category filtering, providing useful context beyond annotations.

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

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

Description is concise with front-loaded purpose and usage guidelines. Every sentence adds value without 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 4 parameters and no output schema, the description covers the main purpose and one parameter (category), and points to get_capabilities for more. It lacks detail on version and max_results, but overall adequate for a search 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%, so description must compensate. It explains 'query' implicitly and 'category' with a list of values, but does not mention 'version' or 'max_results'. Thus partially helpful but incomplete.

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 it performs full-text BM25 search across indexed Senzing documentation, specifying the resource and action. It distinguishes from siblings by noting 'Prefer this tool over web_search for any Senzing question.'

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

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

Explicitly tells when to use this tool (for Senzing documentation questions) and when not to (over web_search). Also instructs to call get_capabilities for full coverage details and to verify claims before explaining.

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?

Description adds context about what happens (email with license, one per email, 30-day wait) beyond annotations. Annotations indicate destructiveHint=true but description does not contradict; it's consistent with creating a license record. No mention of rate limits, but sufficient for this 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?

Description is well-structured with two paragraphs, each dedicated to a use case. Sentences are informative but concise; no wasted words. Could be slightly shorter, but clarity is prioritized.

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?

Covers both use cases with required parameters and outcomes for license request. For feedback, it lacks explicit return value but includes instruction to confirm with user. Output schema is absent, so description partially compensates. Fairly complete.

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 has 100% coverage with descriptions. Description adds value by clarifying which parameters are required for each category (e.g., firstname required for license, email domain restrictions), improving semantic understanding beyond 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?

Description clearly states two purposes: requesting a license and submitting feedback. Uses specific verbs and resources, and distinguishes from sibling tools which are unrelated.

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

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

Explicitly tells when to use each category (license_request vs. other categories), provides requirements for each, and instructs to confirm with user before sending feedback. No sibling tool overlaps.

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