SpecProof

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it returns a plan with requirement_ids and can be fed to generate_tests. No contradictions.

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 with a clear purpose statement followed by an Args list. Every sentence adds value, no wasted words. It's well-structured 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 moderate complexity and presence of an output schema, the description covers purpose, parameter usage, and output format (cited suite plan). It even indicates integration with generate_tests, making it contextually 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?

With 0% schema description coverage, the description provides full parameter explanations: spec_base (with examples), keyword (with examples), include_references (default), and limit (default and max). This compensates entirely for the missing schema descriptions.

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

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

The description clearly states the tool assembles normative requirements for a procedure across a spec and its references, distinguishing it from get_requirements (single spec) and semantic_search. It specifies the output as a cited suite plan and hints at subsequent use with generate_tests.

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 explains when to use: for procedures like registration or handover that span multiple specs. It provides context but doesn't explicitly list when not to use or compare to alternatives like search_specifications.

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

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

The description adds significant behavioral context beyond annotations: it explains the nature of the diff (normative vs textual), specifies that moved or recased clauses are considered unchanged, and implies the output is bucketed by change type. Annotations already indicate read-only and idempotent behavior, so the description complements them well without 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?

The description is well-structured, starting with the core purpose, then clarifying non-textual nature, and finally detailing each parameter. It is concise but a few lines could be trimmed (e.g., repeating 'default' in multiple places).

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 presence of an output schema (not shown), the description doesn't need to detail return values. It covers the tool's core behavior and parameter specifications. However, it lacks information about error handling or assumptions about version label existence, which could be useful for 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?

With schema description coverage at 0%, the description carries full burden for parameter meaning, and it succeeds. Each parameter is clearly explained with purpose, type, default, and example values, adding significant value beyond the raw 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 that the tool diffs two versions of a specification at the NORMATIVE level, identifying added, removed, or reworded requirements. It explicitly distinguishes itself from a textual diff, making the purpose highly specific 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?

The description explains what the tool does not do (e.g., not a textual diff) and clarifies that moved or recased clauses count as unchanged, providing context for when to use it. However, it does not explicitly compare to sibling tools or state when not to use it.

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 declare readOnlyHint=true, which is consistent with generating output without modifying state. The description adds valuable behavioral details: it grounds tests in requirement sentences, cites spec sections, and abstains from inventing tests for non-testable requirements. 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?

The description is reasonably concise with two paragraphs and an Args list. The first paragraph is slightly verbose but still clear. The structure is logical: purpose, behavior, then parameters. Every sentence adds value, though minor tightening could improve conciseness.

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 output schema exists (though not shown), the description does not need to detail return values. It covers key behaviors (citation, abstention) and parameter semantics. For a generation tool, this is adequate; it lacks details on error cases or size limits, but overall complete enough.

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 0%, so the description carries the full burden. It provides a clear Args section explaining both parameters: requirement_id (integer, from get_requirements) and target (string, defaults to pytest, with options). This adds meaningful context beyond the schema's field names and types.

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: generating a cited, runnable conformance test for a normative requirement. It uses specific verbs ('Generate', 'verifies') and identifies the resource ('conformance test'). Sibling tools are all read-only queries, so there is no ambiguity.

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 explains when to use the tool: to verify a normative requirement. It also mentions when it abstains (non-testable requirements). However, it does not explicitly contrast with siblings or provide a when-not-to-use scenario, though the context makes it clear given the sibling list is all read operations.

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 safe read-only behavior (readOnlyHint, idempotentHint, destructiveHint). The description adds minimal context ('comprehensive database and system statistics') but does not disclose additional behavioral traits like required permissions or rate limits.

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

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

The description is a single sentence that clearly states the tool's purpose. It is appropriately sized with no extraneous words, making it easy for an AI agent to parse quickly.

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 simple nature (no parameters, annotations present, output schema exists), the description provides adequate but minimal context. It does not explain what 'comprehensive statistics' include, but the output schema can fill that gap.

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

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

The tool has no parameters, so the description need not add parameter info. According to guidelines, 0 parameters sets a baseline of 4. The description does not miss any necessary parameter details because there are none.

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

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

The description uses the specific verb 'Get' and identifies the resource as 'comprehensive database and system statistics'. This clearly distinguishes it from sibling tools like get_document_content or get_spec_metadata, which focus on specific entities.

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 does not explicitly state when to use this tool versus alternatives. It implies it is for broad overview statistics, but no when-not-to-use guidance or alternative names are provided, leaving the agent to infer 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 provide readOnlyHint=true and idempotentHint=true. The description adds minimal behavioral context (filtering by page_range/section) but does not disclose any additional constraints. It is not contradictory.

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

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

The description is a single-sentence purpose followed by a parameter list. Every line is necessary and well-structured, with no redundant 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?

For a simple tool with 3 parameters and an output schema, the description covers purpose and parameter semantics. It could mention that content is returned as text, but the output schema handles that. Overall 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 schema has 0% description coverage, so the description adds value by explaining each parameter's purpose and providing format examples (e.g., page_range like '10-15'). This goes beyond the schema's type-only information.

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 retrieves specific content from a specification document, using a clear verb ('get') and resource. It distinguishes from sibling tools like list_documents (listing) and get_spec_metadata (metadata).

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 search_specifications or semantic_search. The description only explains what it does, not the context or exclusions.

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 provided, so the description carries full burden. It discloses ranking by reference count and filter options, but lacks explicit read-only hint, rate limits, or side effects. The description is adequate but not detailed.

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 front-loaded with the core purpose. The inline Args section is somewhat redundant with schema but still efficient. No unnecessary sentences.

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 required fields, and an output schema (reducing need to describe returns), the description covers the key aspects: ranking, filters, and default limit. Missing details like sort order or output content are less critical due to output schema.

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

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

Schema description coverage is 0%, but the description adds meaningful parameter details: doc_type filter values ('3gpp' or 'ietf'), series filter by number, limit with default 20. This compensates for the empty schema, though series description could be more precise.

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 gets the most referenced specifications ranked by incoming reference count. It uses a specific verb and resource, and it distinguishes from sibling tools like get_spec_references which focus on references of a specific spec.

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 explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it or provide context about its suitability compared to siblings like get_document_content or get_spec_references.

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, the description carries full behavioral disclosure. It specifies that the graph expands N hops (depth 1-3), applies an optional reference_type filter, and returns JSON with nodes and edges each containing specific fields. It does not mention any destructive side effects or authorization needs, but for a read operation this is sufficient.

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: a one-line purpose statement, followed by a summary of the return JSON, then a bullet list of parameters. Every sentence adds value without redundancy. It is front-loaded with the core purpose.

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 (graph generation with multiple parameters) and the absence of schema descriptions, the description covers input semantics, return structure, and key constraints (depth range, filter options). It does not mention pagination, performance limits, or error handling, but is complete enough for effective 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 coverage is 0%, so the description must compensate. It fully describes each parameter: spec_number as 'Center specification number', depth with range and default, and reference_type with filter values and optionality. This adds essential meaning missing from the 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 states 'Get a relationship graph centered on a specification, expanding N hops,' clearly identifying the verb (get) and resource (relationship graph centered on a specification). It distinguishes from siblings like get_spec_references (which returns linear references) and get_most_referenced_specs (which returns top specs), as it returns a graph suitable for visualization.

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: it is used to obtain a relationship graph for visualization, but it does not explicitly state when to use this tool versus alternatives like get_spec_references or get_series_overview. No 'when not to use' guidance is given, though the graph nature implies it's for broader relationship exploration.

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 behavior. The description adds that results are cited to source clauses, but does not add further behavioral context like authentication requirements or rate limits. It does not contradict 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 very concise with no wasted words. It uses a clear Args section to list parameters and their meanings. Every sentence provides value.

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 an output schema and 4 optional parameters, the description provides sufficient context for usage. It could be slightly more explicit about what is returned beyond cited requirements, but overall it is 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?

With 0% schema description coverage, the description fully compensates by explaining each parameter: spec_number filter, obligation filter, search keyword, and limit with default and max values. This adds significant meaning beyond the empty 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 clearly defines the tool's verb (list) and resource (normative requirements), and specifies they are extracted from specifications with citations. This distinguishes it from sibling tools like search_specifications and get_spec_metadata.

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 lists optional filters but does not explicitly state when to use this tool versus alternatives. No guidance is provided on exclusions or when not to use it. Usage context is implied but not clarified.

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

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

The description adds context beyond annotations: it explains the immutable nature of RFCs and that the lineage is a relationship graph, not a diff. This complements the readOnlyHint and idempotentHint annotations without 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?

The description is concise: two sentences plus a parameter note. It front-loads the core purpose and includes essential context. There is no waste, though the parameter note could be slightly more integrated.

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 one required parameter and an output schema, the description adequately covers the concept, input format, and usage scenario. It provides sufficient context for correct invocation without over-explaining.

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's Args section provides examples of acceptable input formats ('7231', 'rfc7231', 'RFC 7231'), adding vital meaning beyond the schema's mere type and title.

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 as returning an RFC's revision history, specifying it is an Obsoletes/Updates graph due to RFC immutability. It distinguishes itself from a version diff and states the use case of checking supersedence, making it distinct from sibling tools like get_spec_metadata or get_spec_references.

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 a clear use case: find out if a depended-upon RFC has been superseded. It does not explicitly exclude alternative tools or provide when-not-to-use guidance, but the context is sufficient for an agent to decide when to invoke 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that the definition is returned verbatim from the spec, 'exact rather than recalled', providing reliability context. No contradictions.

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 with a purpose paragraph, usage guidance, and parameter list. Every sentence adds value; no waste. Efficient and front-loaded.

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

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

Covers purpose, usage, and parameters adequately. Does not discuss error handling or edge cases, but output schema exists to define return values. For a tool with many siblings, it could differentiate more, but overall complete enough.

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?

Input schema has 0% description coverage, but the description includes an 'Args:' section with brief explanations and examples for each parameter, adding meaning beyond the schema. Descriptions are minimal but sufficient.

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 looks up formal structure definitions (ASN.1, JSON Schema, OpenAPI) from specs, with a specific verb 'look up' and resource 'machine-checkable structure'. It distinguishes from prose search, making its purpose 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?

Explicitly recommends preferring this tool over prose search for structural questions. Lacks explicit exclusions for other siblings, but the contrast with prose search provides clear usage context.

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 provided, so the description alone must convey behavior. The phrase 'Get an overview' implies a read operation, which is sufficient. However, it does not disclose potential costs, caching, or authentication needs, which would be helpful for a tool returning aggregated statistics.

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?

Single sentence, no wasted words. Clearly front-loaded with the action ('Get an overview') and specifics.

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

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

For a simple, parameterless tool with an output schema, the description provides enough context about the return content (document counts, reference statistics, working group assignments). No additional information is needed.

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

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

The tool has zero parameters, so the schema is fully covered. The description adds no parameter information, but none is needed. Baseline score of 4 applies as per rules for 0 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 returns an overview of all specification series, explicitly listing included data (document counts, reference statistics, working group assignments). This distinguishes it from sibling tools like get_most_referenced_specs or get_database_stats.

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 explicit guidance on when to use this tool versus alternatives. However, the purpose is clear, and the lack of parameters implies it's a global overview. For a zero-parameter read tool, this is minimally adequate.

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 exist, so description must cover behavior. It explains the function but omits details like pagination, if results include indirect dependents, or default limit behavior beyond the parameter default.

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?

Extremely concise: two-phrase purpose line followed by parameter list with no extraneous text. Information is front-loaded.

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

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

Tool is simple; description covers purpose and parameters. Output schema exists so return format is handled. Lacks error cases or edge conditions, but adequate for a straightforward query.

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?

Description explains both parameters with clear definitions (spec_number as target, max_results as cap and default), adding value beyond schema field names despite 0% schema coverage signal.

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 retrieves all specifications referencing a given spec, using 'reverse lookup' which distinguishes it from forward reference tools like get_spec_references.

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 term 'reverse lookup' implies when to use it versus forward references, but no explicit alternatives or when-not-to-use guidance 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?

No annotations are present, so the description carries full responsibility. It does not disclose whether the tool is read-only, any authorization requirements, rate limits, or what 'enriched' metadata entails. The behavior is implied as a read operation, but not explicitly stated, and side effects or limitations are absent.

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, starting with the purpose, and then listing parameters in a clean bullet-like format. Each sentence is functional. Minor redundancy ('Filter by' repeated) does not detract from overall efficiency. At ~5 lines, it is appropriately sized for a filtering tool.

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 5 optional parameters, no annotations, and an output schema, the description is moderately complete. It covers parameter meaning but omits return format, pagination details, or what 'enriched' means. For a complex tool, it could explain metadata richness or constraints, leaving some gaps.

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

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

With 0% schema description coverage, the description adds significant value. It explains each parameter's purpose (e.g., spec_number for partial match, series with example '26'), includes examples (e.g., 'SA4' for working_group), and clarifies the default for limit. This compensates for the sparse schema and aids correct 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 retrieves enriched metadata for specifications with filtering. It identifies the resource (specifications) and action (get enriched metadata), distinguishing it from sibling tools like get_spec_dependents or get_spec_references. However, it does not explicitly contrast with search_specifications, which could overlap in purpose.

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. It lists parameters but does not explain appropriate contexts, such as searching by text vs filtering by metadata. Sibling tools like search_specifications or get_spec_dependents are not mentioned, leaving the agent to infer usage without explicit direction.

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 exist, so description carries full burden. It describes inputs but not behavior (e.g., return type, side effects). Output schema exists, but description doesn't clarify if references include full details or just IDs.

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 clear arg documentation. 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 a simple two-parameter tool with an output schema, description covers basic functionality. However, it misses context like error handling or pagination. Sibling tools exist but no guidance on differentiation.

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 0%, but description adds meaning: example for spec_number and filter options for reference_type. This compensates well for the lack of schema descriptions.

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

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

Description clearly states 'Get all specifications referenced by a given spec,' which is a specific verb+resource. This distinguishes it from siblings like get_most_referenced_specs and get_spec_dependents.

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 explicit when-to-use or alternatives provided. The description implies usage for getting references, but does not guide the agent on when to choose this over similar tools like get_spec_dependents.

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 convey safety (read-only, idempotent, not destructive). The description adds parameter explanations and constraints (default, max) but lacks details on result ordering, pagination beyond limit, or response structure. 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?

The description is extremely concise: one sentence for purpose followed by a list of arguments. No fluff, front-loaded with the action.

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 simplicity and the presence of an output schema, the description is sufficiently complete for a list operation. It could mention pagination but the limit parameter and schema cover basic usage.

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 explains all three parameters: doc_type examples, search_pattern purpose, and limit with default and max. Adds clear context.

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 ('List') and resource ('available specification documents'), and the parameter details distinguish it from sibling tools that fetch single documents or perform searches. However, 'available' is somewhat vague.

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 explicit guidance is given on when to use this tool versus sibling tools like search_specifications or semantic_search. The description assumes the agent understands the context.

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 and idempotentHint=true, so the description's behavioral addition is limited to stating 'full-text search' and parameter defaults. No contradictions, but no extra disclosure of rate limits, auth needs, or result behavior.

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 with a docstring-style Args block. Every sentence is informative 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 the output schema exists, the description adequately covers parameters and search scope. However, it could mention result ordering or that search is across multiple sources, which would enhance 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?

Schema description coverage is 0%, so the description fully compensates by explaining each parameter's purpose, valid values for doc_type, and constraints for max_results (default 10, max 50). This adds significant meaning beyond the 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 verb 'Search across' and the resource '3GPP, IETF, and Multimedia specification documents', specifying the scope. However, it does not differentiate from sibling tools like semantic_search, which also performs search.

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 lacks any guidance on when to use this tool versus alternatives (e.g., semantic_search, get_document_content). It only implies usage for full-text search but provides no exclusions or comparisons.

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 read-only, idempotent, non-destructive behavior. The description adds behavioral context such as FAISS acceleration, parameter explanations, and index type options (hnsw, ivf, flat) beyond annotations. No contradictions.

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 with a summary line and a parameter list. No irrelevant information; every sentence adds value. Front-loaded with the core purpose.

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 and an output schema, the description adequately explains each parameter and the FAISS technology. However, it does not specify the corpus or scope being searched (e.g., 'specifications'), which could be inferred but not explicit. Output schema handles return format, so no deduction.

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% description coverage, so the description carries full burden. It provides clear explanations for all four parameters: query as natural language, max_results with default and max, similarity_threshold with range, and index_type with allowed values and auto-selection. This adds significant meaning.

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 performs semantic search using vector embeddings with FAISS acceleration, which is a specific verb and resource. It distinguishes from siblings like 'search_specifications' and 'get_database_stats' as the only semantic search 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?

No guidance is provided on when to use this tool versus alternatives like 'search_specifications'. There is no mention of appropriate contexts, exclusions, or comparisons to sibling tools.

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