Horizons Nasa

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details beyond these: default model (Workers AI Llama-3.3-70b, free), optional Anthropic probing with a BYO key, and return structure (per-model fields + combined view). 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?

Three sentences front-load the core purpose, detail model options and returns, and list use cases. Every sentence adds value with no 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?

For a tool with no output schema, the description explains return format (per-model score, confidence, signals, raw_response + combined view). It does not detail the combined view structure or error handling, but annotations cover safety. Fairly complete given the simple probe functionality.

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% with detailed per-parameter descriptions (entity, models, _apiKey, context). The description does not add significant meaning beyond the schema, so baseline 3 is appropriate.

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 probes LLMs for knowledge about an entity and scores visibility (0-100), with specific verb 'probe' and resource 'LLMs'. It does not explicitly differentiate from siblings like 'scan_competitor_ai_presence', but the purpose is 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 provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It does not mention when not to use or alternatives, so it lacks exclusions but offers strong 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, openWorldHint, idempotentHint, and destructiveHint. The description adds that it routes questions, fills arguments, and returns structured answers with citations. 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 somewhat verbose but front-loaded with the key guidance. Examples are helpful. Could be tightened without losing meaning.

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 (many aliases, no output schema), the description adequately covers purpose, usage, and output format. Annotations are rich, so less burden on description.

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%, so baseline is 3. The description mentions 'fills arguments' but doesn't add significant detail beyond the schema's property 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 is for factual queries about structured data, listing many domains. It uses specific verbs ('ask', 'routes', 'returns') and distinguishes from web search by emphasizing structured citations and coverage of 780 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?

Explicitly says 'PREFER OVER WEB SEARCH' and lists when to use (questions about specific data types). Provides examples and user intent phrases. However, it doesn't mention specific sibling tools as 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?

The description adds extensive behavioral disclosure beyond annotations, including resolver confidence level handling (low_confidence_match suppresses analysis), closed market detection (status:market_closed_or_inactive), wide-spread market tradeability warnings, resolver contract details (match_confidence, match_score, alternatives), parent event extractor behavior, and fallback mechanisms for news sources. No contradiction with readOnlyHint, idempotentHint, or destructiveHint 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 dense and well-structured with section headings (e.g., CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES), but it is very long. While most sentences add value, it could be condensed without losing critical information. The structure helps but the length reduces 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 tool's complexity (multiple classifiers, fan-out patterns, resolver logic, response shapes, safety mechanisms, parent event extraction, and error handling), the description covers all necessary aspects for an agent to use it correctly. There is no output schema, but the description explains response shapes thoroughly.

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?

All three parameters (market, depth, include_raw) have descriptions in the schema, and the description adds context: market can be slug/URL/question text, depth lists quick/thorough with defaults, and include_raw explains when to use true vs false. This exceeds baseline given 100% schema coverage.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which have different focuses.

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 explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides detailed examples of classifiers and fan-out. However, it does not explicitly state when not to use this tool or direct users to sibling tools for related tasks, which would strengthen the 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds essential behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. 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 front-loaded with intent phrases and every sentence adds value, but it is slightly verbose with extensive examples and technical details. Still, it maintains clarity and efficiency.

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?

Despite no output schema, the description explains the return format: paired data with sorted results and pipeworx:// citation URIs per entity. Combined with the detailed parameter descriptions, the agent has full context to invoke and interpret 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 coverage is 100% for both parameters. Description adds meaning by explaining what each type returns (financials vs. adverse events) and giving concrete examples for values (tickers/CIKs, drug names). It also reinforces the maxItems/minItems constraints.

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 compares 2-5 companies or drugs side-by-side in one parallel call. It uses specific verbs and resources, and distinguishes from sequential single-pack lookups used by sibling tools like entity_profile.

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 explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries like 'Compare X and Y'. It clearly defines when to use this tool versus 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?

The description goes beyond annotations by explaining the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This adds valuable behavioral context that annotations (readOnlyHint, idempotentHint) do not cover.

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 three sentences that efficiently convey purpose, usage, example domains, and result format. It is front-loaded with the core action and includes all essential information 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?

For a tool that accepts a query and returns a list of tools, the description covers purpose, input (including aliases), output format, and usage context. No output schema exists, but the description adequately explains what the agent can expect, making it complete for this complexity.

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 baseline is 3. The description explains the 'query' parameter's role as a natural language description and lists aliases (task, q, description, search). It also mentions the 'limit' parameter. This adds context beyond the schema, which already describes each parameter clearly.

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: 'Find tools by describing the data or task.' It uses specific verbs like browse, search, look up, or discover, and lists the domains covered. This distinguishes it from sibling tools, which are specific data tools rather than a discovery 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 explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use the tool. It does not explicitly state when not to use it or mention alternatives, but the guidance is strong enough.

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, openWorldHint=true, idempotentHint=true. Description adds significant behavioral details: fans out across multiple sources, returns specific fields (CIK, filings with URIs, fundamentals, patents with sunset note, news fallback, LEI), and mentions soft-fails. 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?

Description is relatively long but front-loaded with example queries. Every sentence provides necessary information; uses semicolons for structured enumeration. No redundancy, but could be slightly more terse.

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

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

With no output schema, the description thoroughly details the return structure: specific fields, counts (up to 5 filings), URI format, fallback behavior, and limitations. References sibling tool for name resolution. Highly complete for a complex, multi-source 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 coverage is 100% with descriptions for both parameters. Description adds value by clarifying accepted values (ticker or zero-padded CIK) and explicitly stating names are not supported, reinforcing the schema's enum and string hints.

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?

Starts with concrete user queries, then states it delivers a 'full cross-source profile of a US public company in ONE parallel call'. Distinguishes from chaining single-pack lookups, and contrasts with sibling tools like resolve_entity and compare_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?

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and warns 'names not supported (use resolve_entity first if you only have a name)'. Provides clear when-to-use and when-not-to-use.

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, and non-destructive traits. The description adds the default 'OBSERVER' table type but provides no other behavioral context (e.g., data source, rate limits). 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?

Extremely concise single sentence with minimal waste. However, it does not prioritize or front-load key information like the fact that it produces a table.

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 tool with 6 parameters and an output schema, the description is too brief. It does not explain return values or usage patterns beyond the bare minimum, leaving much to inference from the schema alone.

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%, so parameters are fully documented in the schema. The description adds no additional meaning beyond the schema. Baseline 3 is appropriate.

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 'Generate an ephemeris (default observer table)', which is a specific verb-resource combination. It hints at the default table type but does not explicitly differentiate from sibling tools like 'vectors'.

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 on when to use this tool versus alternatives such as 'vectors' or 'validate_claim'. The description lacks context on prerequisites or typical use cases, leaving the agent to infer.

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 destructiveHint=true and idempotentHint=true. Description adds context about clearing stale/sensitive data but does not add much beyond the annotations. 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?

Two concise sentences, front-loaded with action, no 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 one parameter and no output schema, the description covers purpose and usage adequately. Missing return value or error behavior, but acceptable for a simple deletion 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 100% with parameter 'key' clearly described. Description does not add additional 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?

Description clearly states 'Delete a previously stored memory by key', specifying the verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by being the delete operation.

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 explicit when-to-use guidance: stale context, task done, clearing sensitive data. Mentions pairing with remember and recall, but does not state when not to use or provide 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?

Annotations already indicate safe, idempotent, non-destructive behavior. The description adds value by explaining the fetch-and-extract process and output format (markdown blob). No mention of rate limits or errors, but sufficient given 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 concise sentences followed by a list of use cases. No wasted words; front-loaded with the core action. Every sentence adds 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?

For a simple tool with two well-documented parameters and no output schema, the description adequately explains the output (text blob). Missing details like error handling, but overall complete enough for an agent to use 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?

Input schema covers both parameters with detailed descriptions. The tool description adds no new parameter information beyond what's in the schema. With 100% coverage, baseline 3 is appropriate.

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 generates an llms.txt file for a URL, specifies the process (fetch, extract title/description/key links), and lists concrete use cases. It distinguishes from siblings implicitly by its unique 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?

The 'Useful for' section provides three explicit scenarios (client indexing, own project drafting, competitor auditing). However, it does not mention when not to use or compare to alternatives like ai_visibility_check, leaving room for ambiguity.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds minimal behavioral context beyond the basic mapping. It does not disclose error handling, uniqueness, or edge cases. Since annotations carry most of the burden, the description's contribution is low.

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 at one sentence, which is appropriate for a simple tool. However, it lacks any structure (e.g., no usage notes or examples). It is not overly verbose, but could be more informative without adding length.

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 is too minimal. It does not explain what an SPK ID is, how the lookup works, or what the output schema contains. The examples are helpful but not enough for complete understanding.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'object name' but does not specify the expected format, allowed values, or case sensitivity. The examples ('Mars', 'ISS') hint at proper nouns but are insufficient for unambiguous 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 that the tool resolves an object name to an SPK ID. It uses a specific verb ('resolve') and resource ('object name → SPK id'), which is clear. However, there is no differentiation from the sibling tool 'resolve_entity', so it loses one point.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'resolve_entity'. It does not specify prerequisites, context, or conditions for use. This is a significant gap.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond stating it is a convenience with a specific table_type. The bar is lowered by annotations, but the description still fails to disclose any additional behavioral traits.

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), but it is underspecified for a tool with 5 parameters. It sacrifices clarity for brevity, leaving the agent to guess the meaning and usage.

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 5 parameters, 3 required, an output schema (not shown), and no parameter descriptions, the description is severely incomplete. It does not explain what the tool returns, how to structure inputs, or what 'observers' entails.

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%, and the description provides no information about any of the 5 parameters. Neither the schema nor the description explains the meaning or usage of parameters like command, start_time, stop_time, center, or step_size. The examples offer some context but no semantic explanation.

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 indicates this tool is a convenience version of ephemeris with table_type=OBSERVER, distinguishing it from the generic ephemeris sibling. However, it relies on prior knowledge of what ephemeris does, which could be clarified.

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 says 'convenience' but provides no explicit guidance on when to use this tool versus the alternative ephemeris tool. No when-to-use or when-not-to-use information is given.

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 the annotations (which are all false, providing no behavioral cues), the description discloses important traits: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and the team reads digests daily. This fully informs the agent about constraints and impact.

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 (4 sentences) and front-loaded with purpose. Every sentence adds unique value: purpose, usage cases, writing guidance, and behavioral notes. No 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's moderate complexity (3 params, 1 nested object, no output schema), the description covers all essential aspects: purpose, when to use, parameter semantics, behavioral constraints (rate limits, quota), and how the feedback is used. Combined with the schema, it provides a complete picture.

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% and the schema provides good descriptions for each parameter. The description adds value by explaining the meaning of each 'type' enum and giving guidance on how to write the 'message' (be specific, 1-2 sentences). This is above baseline but not transformative.

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: to send feedback (bug, feature, data_gap, praise) to the Pipeworx team. It uses specific verbs ('tell') and resources ('the Pipeworx team') and distinguishes itself from sibling tools, none of which are feedback-related.

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 explicitly states when to use each feedback type (bug, feature, data_gap, praise) and what not to do (don't paste the end-user prompt). It also clarifies that it's for tool/pack-related feedback, not general questions.

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, idempotent, etc. Description adds value: self-aggregating, no PII, caching behavior. 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?

Four sentences, each packing meaningful detail, front-loaded with main result. No fluff.

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?

Complete for a single-parameter tool with full annotations. Covers return content, caching, and use cases.

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%. Description adds default value and usage guidance for window parameter, enhancing its 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 returns top tools, packs, and call volume over a window. It uses a specific verb ('returns') and resource, and is distinct from siblings like 'discover_tools'.

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?

Three explicit use cases are listed, plus window selection guidance. No explicit when-not or alternatives, but context is well covered.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description does not contradict these. It adds details about error behavior (no-arg failure), Jaccard similarity threshold, partition filtering for placeholders, and response structure, going 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?

The description is long but efficiently structured with ALL CAPS for requirements and clear separation of modes. Every sentence adds value, though some redundancy 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?

Despite no output schema, the description thoroughly covers the response fields (opportunities, partition_check), error cases (no args, low similarity, placeholder filter), and mode-specific behaviors. It is complete for a complex 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?

Input schema has 100% description coverage, so baseline is 3. However, the description adds significant value by clarifying modes, providing examples (slug format, URL acceptance), and explaining the context for each parameter.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between single-event mode ('event') and cross-event mode ('topic'), and provides examples, which differentiates it from sibling tools like polymarket_edges.

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 explicitly requires one of 'event' or 'topic' and warns that calling with no arguments fails. It recommends 'event' for specific markets and 'topic' for cross-event scanning, explaining what each mode catches.

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 discloses extensive behavioral traits beyond annotations: data sources (FRED, GDELT), model details (lognormal, news momentum, partition overround), caching strategy (1h KV-level), and diagnostics. No contradictions with annotations (readOnlyHint=true, etc.).

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 dense and technical, consuming multiple sentences to detail models and filters. While comprehensive, it could be more concise for an AI agent. The structure is logical but front-loading could be stronger.

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 100% schema coverage and no output schema, the description explains return structure (by_segment, diagnostics) and caveats (Fed bets). It covers the tool's complexity well, though lacks explicit return value descriptions for non-diagnostic fields.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds usage context for several parameters (e.g., slippage_pp explains Polymarket fees, min_partition_leg_kelly explains why min_kelly doesn't apply). This enhances interpretability, so scores above baseline.

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 explicitly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today' and distinguishes between three model families, clearly differentiating from siblings like polymarket_arbitrage and polymarket_kalshi_spread.

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 context for when to use ('what should I bet on today' - discover opportunities without paging) and details knobs for filtering. However, it lacks explicit when-not-to-use or direct comparison to sibling tools for exclusion cases.

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=true, idempotentHint=true, destructiveHint=false), the description details response structure, safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), and edge cases. 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 verbose but well-structured with clear sections (modes, response, safety fields). It front-loads the main purpose and provides necessary detail for a complex tool. Slightly longer than ideal but justified.

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?

Despite lacking an output schema, the description thoroughly explains the response format (leg-by-leg prices, matched spread, safety fields) and handles edge cases like non-equivalent bet shapes and temporal misalignment. Complete for a complex tool with 3 optional parameters.

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% (all 3 parameters described). The description adds significant context: explains the 10 topic macros, that explicit parameters override topic, and how response fields relate to parameters. This goes well 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 it's a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' and explains the two modes (topic and explicit). It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue spreads and safety checks.

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 guidance on when to use each mode (topic for shortcuts, explicit for custom pairings) and warns that pre-mapped topics often return compatibility warnings. It does not explicitly compare to siblings but explains when spreads are meaningful (equivalent bet shapes) and when not.

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 and idempotentHint, so the bar is lower. The description adds behavioral context: scoping to an identifier, retrieval vs listing, and the concept of re-derivation. No contradictions. While not exhaustive, it provides useful behavior 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: first states primary action (retrieve/list), second adds use cases, scope, and pairing. No filler, front-loaded with the most important information. Every sentence earns its place.

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

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

With only one optional parameter, no output schema, and clear annotations, the description covers purpose, usage, and pairing. It does not specify the return format (e.g., single value vs array), but for a simple retrieval tool, the description is nearly 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 coverage is 100% and the schema description already says 'omit to list all keys.' The description adds high-level purpose ('look up context...') but does not add new semantic detail about the parameter itself beyond what the schema provides. Baseline score applies.

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 a saved value or lists all keys when the argument is omitted. It provides concrete examples (ticker, address, notes) and distinguishes from siblings 'remember' and 'forget' by naming them and explaining pairing.

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 states when to use: 'to look up context... without re-deriving it from scratch.' It also guides by mentioning how to list all keys and pairs with 'remember' and 'forget,' giving clear context for alternative actions.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: source fan-out details (SEC, GDELT, GNews, USPTO), fallback behavior, soft-fail for USPTO, and return format including pipeworx:// URIs. 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 a single, well-structured paragraph that front-loads the purpose with example queries. Every sentence provides unique, useful information 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?

Despite no output schema, the description explains the return format (structured changes grouped by source, total_changes count, citation URIs). It covers all three required parameters and mentions constraints (only company type supported). The description is complete for effective tool invocation.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the 'since' parameter accepts ISO dates or relative shorthand and suggests typical values, and clarifies that 'value' can be a ticker or CIK.

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 returns a change feed for a company over a window, fanning out to multiple sources. It distinguishes itself from the sibling tool 'entity_profile' by specifying when to use each.

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 explicitly provides example queries and directly contrasts with 'entity_profile' for static profile needs, giving 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?

Discloses key-value pair storage, scoping by identifier, and retention details (persistent for authenticated, 24h for anonymous). Annotations already convey idempotency and non-destructiveness; description adds useful context 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?

Four sentences, each with a clear purpose: purpose first, then usage guidance, then technical details, then pairing instructions. No 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?

For a simple write tool with no output schema, it explains persistence, scoping, and pairing with recall/forget. Could explicitly note overwrite behavior, but idempotentHint compensates. Leave at 4.

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 both parameters with descriptions (100% coverage). Description provides usage examples for key (e.g., 'subject_property') and value, adding slight value but not significantly 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 the tool stores data for reuse later, with specific examples (resolved ticker, target address) and distinguishes from siblings recall and forget.

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 states when to use ('when you discover something worth carrying forward') and mentions persistence differences based on authentication. Does not explicitly list exclusions but names alternatives (recall, forget).

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, etc. The description adds value by explaining internal cascading through several endpoints, replacing 2-3 manual lookups. 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 concise (about 100 words), well-structured with bullet points for entity types, and front-loaded with the core purpose. Every sentence adds 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 no output schema, the description fully explains return values and citations. It covers internal behavior and usage context, making it complete for a lookup 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?

The description greatly enriches the schema by specifying return values for each type (company: ticker, CIK, company_name, citation URI; drug: RxCUI, ingredient, brand, citation URI) and providing examples and auto-disambiguation 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?

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples (ticker, CIK, RxCUI) and supported types (company, drug). It distinguishes itself from sibling tools by being the first step for name-to-ID conversion.

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 explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear context. However, it does not mention when not to use it or point to alternative tools like entity_profile.

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, idempotentHint, and non-destructive nature. Description adds context on the process (probing each entity, ranking) and output details (score, confidence, signal density), which is sufficient given the annotation coverage. 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?

Three sentences that are front-loaded with the main action, followed by a use case and output summary. No unnecessary words or redundancy.

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

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

With 4 parameters and no output schema, the description provides process, output structure, and use case. It does not cover error handling or rate limits, but annotations cover safety adequately. Sufficient for an AI agent.

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% with detailed parameter descriptions. The main description adds only a summary of entity usage and comparison logic, which does not significantly enhance understanding beyond what is already in the schema. Baseline 3 is appropriate.

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 compares AI visibility across multiple entities, ranks them, and identifies most/least recognized. Uses a specific verb 'compare' and resource 'AI visibility', distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (more generic).

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 use case: 'competitive AI-marketing audits' with an example question. Implicitly excludes single-entity comparisons, and references sibling tool ai_visibility_check as the underlying mechanism, guiding the agent when to use this vs other tools.

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

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

Annotations already signal readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral details: fans out to multiple sources, returns specific fields, mentions potential timeouts (5-30s for first measurement), and graceful degradation (sources_failed list). 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 relatively long but efficiently packed with critical information. It front-loads the purpose, then details usage, behavior, and edge cases. Every sentence serves a purpose, though it could be slightly more concise without losing meaning.

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 (multiple external data sources, partial failures, ecosystem limitations), the description is remarkably complete. It covers the composite nature, return fields, timeout warnings, and alternative tools. No output schema exists, but the description effectively compensates.

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% with each parameter described briefly. The description adds useful nuance: scoped packages accepted for the 'package' parameter, and 'version' defaults to latest when omitted. This enriches the schema without being redundant, but the schema already provides basic clarity.

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: a composite check for evaluating an npm package for a project. It uses specific verbs ('should I add', 'check') and clearly distinguishes from sibling tools by specifying the npm ecosystem limitation and referencing alternatives for other ecosystems.

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 explicitly states when to use the tool: when an agent asks about safety, popularity, size, or cost of adding a package. It also specifies when not to use it (non-NPM ecosystems) and provides clear guidance on partial failures and degradation behavior.

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 destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral detail: it uses SEC EDGAR + XBRL, returns a verdict with structured form, actual value, and percent delta. 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 a single, dense paragraph that front-loads the query patterns. Every sentence adds value, and it efficiently communicates purpose, usage, domain, and output without unnecessary verbosity.

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 single parameter and absence of output schema, the description provides sufficient context: domain (company-financial), sources (SEC XBRL), return format (verdict, structured form, citation, delta). It does not mention limitations (e.g., only US companies) but is otherwise 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 coverage is 100% with a single parameter 'claim' described. The description adds context about the acceptable input types (natural-language factual claims) and provides examples, going beyond the schema's minimal description. However, the schema already covers the basics.

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 verifies natural-language claims about company finances using authoritative sources. It provides specific examples of query patterns (e.g., 'Is it true that...', 'fact check') and distinguishes itself by mentioning it replaces 4-6 sequential calls, making its purpose 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It narrows the scope to company-financial claims for public US companies, providing clear guidance on when to use this tool versus 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 already declare readOnly, idempotent, non-destructive, so the description adds minimal behavioral context beyond specifying the VECTORS table type. This is sufficient but not rich.

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, consisting of a single sentence. However, it is too terse and lacks structure, sacrificing clarity for brevity.

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

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

With 5 undocumented parameters and no explanation of what vectors are or how to use this tool effectively, the description is severely incomplete. The agent cannot determine parameter values or when to use this tool over its siblings.

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 5 parameters with no descriptions, and the tool description does not explain any of them. The agent has no guidance on the meaning of 'center', 'command', 'step_size', 'stop_time', 'start_time' beyond their names. This is a critical deficiency.

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 it is a convenience wrapper for ephemeris with table_type=VECTORS, implying it provides vector ephemeris data. However, it does not explain what 'vectors' means in this context, nor how it differs from the general ephemeris tool. The purpose is hinted but not fully defined.

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 usage guidelines provided. The description does not indicate when to use this tool over its sibling 'ephemeris' or others. The term 'convenience' is not elaborated.

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