Fodda Topic & Trend Research

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining polling behavior and expected status outcomes, which is not covered by 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 are concise and front-loaded with purpose, then usage instructions. No unnecessary 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?

Despite no output schema, description explains return status meanings. With one required parameter and clear usage context, the description is fully adequate.

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

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

Only one parameter 'job_id' with description in schema. Schema coverage is 100%, so description adds minimal extra meaning. Baseline score of 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?

Description clearly states the tool checks completeness of market data gathering and retrieves results, using specific verb 'check' and resource 'supplemental status'. It also distinguishes from sibling tool get_supplemental_context by stating to call after it.

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 specifies when to use the tool: after get_supplemental_context, with polling interval of 5-10 seconds until COMPLETE or FAILED. No explicit exclusions or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's addition of 'Returns a branded SVG that renders directly in the chat' is useful but not critical. No contradictions, but description could add more about error cases or limitations.

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 with no fluff. Front-loaded with purpose, followed by enumerated chart types and output. Every sentence is valuable.

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 parameters and output format well. No output schema, but description mentions SVG return. Could mention pricing, rate limits, or error handling, but acceptable for a read-only visualization 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%, and the description adds detailed explanations of the expected data structure for each chart type beyond the schema's short descriptions. This helps agents construct correct inputs.

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 creates a presentation-ready data visualization from research findings and lists all six chart types. The name 'generate_visual' aligns with this. Distinct from siblings which are search or retrieval 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?

No explicit guidance on when to use this tool vs. alternatives. Does not mention when not to use it. Siblings like 'search_graph' or 'get_node' could be alternatives for data access, but no comparison 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns cost information, which is not in annotations, but does not elaborate on other behavioral traits like data freshness or authentication needs.

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: the first states what the tool returns, the second explains when to call it. No unnecessary words, front-loaded with the key information.

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?

The tool is simple with no output schema, but the description adequately covers its purpose and usage. It could optionally mention the structure of the returned capabilities or pricing, but the current text is sufficient for an AI agent to understand when to invoke it.

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 one optional parameter 'userId' with a description. Schema coverage is 100%, so the description does not need to add more. It provides no 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?

The description clearly states the tool returns Fodda's capabilities, features, offerings, and pricing. It explicitly mentions when to use it for any question about what Fodda can do, making the purpose specific and distinct from sibling 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?

The description explicitly advises calling this tool for any question about what Fodda can do or what is available. It does not mention when not to use it or alternative tools, but the context is clear for a general capabilities lookup.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so this is a safe read operation. The description adds valuable context: it is a direct lookup (not a search), costs $0.50 per lookup, and returns items with specific fields (source URL, location, brand names, publication date, category, formatted citation). This goes beyond annotations and helps the agent set expectations.

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: first sentence states the main purpose, second details output, third gives usage guidance, fourth clarifies it is not a text search, and last states price. Every sentence earns its place with no fluff 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?

For a simple lookup tool with no output schema, the description fully explains what the agent gets back: source articles, case studies, statistics with citations and publisher attribution, plus specific fields per item. It also covers cost and the input relationship (after search_graph). No important gaps remain.

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 detailed parameter descriptions (e.g., for_node_id must come from prior search_graph result, not guessed). The description reinforces this by saying 'direct lookup by trend ID' and 'Use after search_graph,' which connects the parameters to the workflow. It adds usage context beyond the schema while the schema handles field-level 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 starts with a specific verb and resource: 'Get the source articles, case studies, and statistics behind a specific trend.' It also clearly distinguishes itself from siblings by stating 'This is a direct lookup by trend ID — not a text search tool,' which differentiates it from search_graph and search_insights.

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

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

Explicitly tells when to use: 'Use after search_graph when you need the supporting proof behind a trend.' It also clarifies the inverse: it is not a text search tool, so it should not be used for open-ended queries. The $0.50 price also sets cost context for usage decisions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds valuable context: for Trend labels it returns a 'complete deterministic list' (useful when search is partial), and implies the tool is meant for exploration. 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?

Three sentences, front-loaded with purpose and examples. No redundant or wasted words. Every sentence adds value: purpose, usage examples, and a specific tip for trends.

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 is sufficiently complete for selection and basic usage. It explains what the tool returns (list of values) and how to use it for different labels. However, lacks details on result format (e.g., array of strings) which would further improve 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?

Input schema has 100% description coverage for all 4 parameters, so baseline is 3. The description adds minor extra meaning: examples of label values and note about property defaults varying by label, but this does not significantly enhance understanding 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 explicitly states the tool lists brands, locations, technologies, audiences, or trends within a specific knowledge graph, using a specific verb ('List') and resource ('label values'). It differentiates from sibling tools like search_graph or list_graphs by focusing on specific categorical exploration.

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 concrete examples of when to use ('what brands are in the retail graph?') and a special use case for trends with label='Trend'. However, it does not explicitly state when not to use or mention alternatives, though the context of sibling tools implicitly guides selection.

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. The description adds value by noting 'Returns live data — not cached from session start', informing the agent of data freshness. 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?

Two sentences: first states purpose, second gives usage examples and data freshness note. No unnecessary words, front-loaded structure.

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?

Complexity is low (0 parameters). Annotations cover safety, description lists return values (balance, plan, graphs, profile). Output schema is absent but the description sufficiently enumerates response 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?

No parameters exist, so schema coverage is 100% trivially. Per guidelines, 0 parameters yields baseline 4. No need for additional parameter info.

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

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

The description states a specific verb ('Check') and resource ('current user's account status'), enumerating exact contents (API call balance, plan, graphs, profile info). It clearly distinguishes from sibling tools like 'check_supplemental_status' and 'get_capabilities'.

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 lists example user queries ('how many API calls do I have?', 'what plan am I on?') that trigger use. While it does not mention when not to use, the guidance is clear and actionable.

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 and idempotent behavior. Description supplements this by disclosing the curated, editorial nature of results and the dependency on prior node IDs, which goes beyond basic safety info.

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, but some redundancy (both first and second mention 'web search cannot provide'). Could be tightened while retaining key information.

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?

Provides context for the type of data returned (curated editorial connections, specific entity types) and the prerequisite call to search_graph. With no output schema, the description vaguely indicates return shape, which is adequate for this tool.

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

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

Schema covers 100% of parameters with detailed descriptions, so description adds little beyond requiring node_id. The baseline of 3 is appropriate as the schema does the heavy lifting.

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 discovers connections to a trend, lists specific entity types (brands, technologies, locations), and distinguishes from the sibling search_graph tool by emphasizing curated editorial links that web search cannot provide.

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 instructs to use after search_graph to map territory or find brands/relationships, and requires node_id from a prior search_graph result, giving clear when-to-use and prerequisite information.

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, destructiveHint=false, idempotentHint=true. Description adds no contradictory info and provides helpful context about input constraints (node_id source), but behavioral details are mostly covered by annotations.

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

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

Two sentences, front-loads purpose in first sentence, usage guidance in second. No wasted words, highly efficient.

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

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

No output schema, but description lists return content (detailed description, lifecycle stage, etc.). Given the read-only nature and good annotations, it's sufficiently complete. Could mention error handling but not critical for tool selection.

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

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

Schema coverage is 100%, but description adds critical context for nodeId: must come from prior search_graph result, not sequential, not the trend name. For userId and graphId, description relies on schema. Overall, description adds value beyond schema for the key 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 gets the full profile of a specific trend, listing attributes (description, lifecycle stage, etc.) and explicitly differentiates from search_graph by noting it's for deeper detail after a summary.

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 (deeper detail on a single trend), prerequisite (node_id from search_graph), and what not to do (guess IDs). Provides clear guidance for correct invocation.

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?

Despite annotations (readOnlyHint=true, destructiveHint=false) already covering safety, the description adds valuable behavioral context: parallel fan-out across 80+ sources, return format (categorized data blocks with source attribution/metadata), and the $10 cost per query. 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 concise, with each sentence serving a purpose: purpose, when to use, data sources/behavior, return format, pricing, and a specific trigger note. It is front-loaded with the core purpose and avoids redundancy with annotations/schema.

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 6 parameters, no output schema, and a non-trivial pricing model, the description covers essential operational details: how the tool executes (parallel), what it returns, cost, and the critical invocation condition (after search_graph). This is fully comprehensible for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself does not add meaning beyond schema—the guidance about domain usage and query format is already embedded in the parameter descriptions. It contributes no additional param semantics beyond what the schema already documents.

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 identifies the tool as a layer for macro, institutional, and real-time market data, with specific verbs ('get', 'retrieves') and a resource ('supplemental context'). It distinguishes itself from siblings by stating it should be called when search_graph indicates thin/empty coverage, and by listing its data sources (Google Trends, FRED, BLS).

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

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

Explicit usage guidance is provided: call when curated coverage is thin/empty or when query is demand/attention-shaped, and specifically after search_graph indicates thin/empty coverage. It also includes a param-level guideline about not passing certain domains for macro queries, and notes pricing, which informs usage decisions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety behavior. The description adds valuable context: the source (corporate earnings reports), the cross-validation pipeline, and the price ($25 per query). This goes beyond annotations, especially the cost disclosure.

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, each earning its place: the first states the core function, the second explains the connection context, and the third states the price. No fluff or redundancy, and the most important 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?

The tool has 5 optional parameters, no output schema, and a simple 'read' nature. The description covers what it returns, the source, and cost. It could mention usage guidance or result format, but given the annotations, this is reasonably complete for the tool's 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 the schema already documents all parameters. The description adds no parameter-specific semantics beyond what the schema provides, so the baseline of 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 returns market-validated consumer trends from earnings reports, with a specific source and pipeline. It is understandable but does not explicitly distinguish itself from sibling tools like search_insights or get_evidence, so it does not fully meet the 5-point criterion of distinguishing from siblings.

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 given about when to use this tool versus alternatives. The description implies a use case (connecting earnings commentary with consumer trends) but does not state exclusions or alternatives. Given the large sibling toolset, this is a notable 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 readOnly, idempotent, and non-destructive behavior. The description adds useful context by listing the specific metadata returned and confirming that only accessible graphs are listed, going beyond what annotations provide.

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

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

Two sentences, front-loaded with the core action and result fields, followed by usage guidance. Every sentence contributes value with zero 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 simple list tool with one optional parameter and no output schema, the description adequately covers what is returned, when to use it, and how it relates to the rest of the toolset. It is self-sufficient for correct 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?

The single optional parameter (userId) is fully described by the schema at 100% coverage. The description adds no new parameter semantics; the schema already explains optionality and authentication, 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 lists all expert knowledge graphs the user can access, enumerates the returned fields (IDs, descriptions, authors, sectors, signal counts, topic coverage), and distinguishes it from sibling search tools by positioning it as the discovery step.

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 instructs to use 'FIRST in any session to discover available sources before searching' and explains that returns graph metadata needed for graphId parameters in other tools, creating clear when-to-use and relationship-to-siblings 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 establish a safe, read-only, idempotent operation, so the low bar is met. The description adds extra behavioral context by stating it returns 'structured text ready for analysis' and discloses the cost ('$20 per URL lookup'), which is useful beyond annotation-provided hints. No contradiction found.

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, each earning its place: action, usage scenario, and return format plus price. The description is front-loaded with the core verb and resource, with no filler or repetition.

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 (one required param, no output schema) and rich annotations, the description adequately covers the return value, cost, and use cases. It does not overpromise or omit critical details, making it nearly complete for a URL-read 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 covers both parameters (url and userId) with descriptions, achieving 100% coverage. The description does not add parameter-specific meaning beyond what the schema already states, so the baseline score of 3 for high schema coverage 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 opens with a specific verb and resource: 'Extract clean text content from any URL.' It goes on to specify example use cases (competitor site, news article) and positions the tool as a cross-referencing aid against Fodda knowledge graphs, clearly differentiating it from the sibling search and graph 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?

Provides explicit usage context: 'Use this when a user shares a link...' and the analysis goal. It does not explicitly name alternatives, but the use case strongly implies this is the go-to tool for external URL reading, distinct from graph-internal 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 provide readOnlyHint and destructiveHint. The description adds parallel search behavior when graphId is omitted, the output structure (cited evidence, source attribution, lifecycle stage), and pricing transparency. This goes beyond annotations without contradicting them.

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 four sentences, front-loaded with purpose, then return detail, default behavior, use cases, and price. Every sentence earns its place with no redundancy or filler.

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 8 parameters and no output schema, the description covers the key aspects: what it returns, how to scope it, and when to use it. It falls short of fully explaining edge cases or interpreting lifecycle stages, but is sufficiently complete for a search tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the graphId default behavior and adds a recommendation, but does not add substantial new meaning to other parameters. It does not compensate 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 tool finds trends, signals, and expert insights across 100+ curated knowledge graphs, naming specific domains and distinguishing it from generic web summaries. This is a specific verb+resource+scope formulation that separates it from sibling tools like search_insights.

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 gives explicit use cases ('market trends, competitor analysis, innovation signals, consumer behavior, cultural shifts') and a decision heuristic ('or any topic where curated expert intelligence outperforms web search'). It does not explicitly exclude alternatives or name sibling tools, but the context is clear enough for 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 include readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral context: it is narrative-only, returns qualitative evidence NOT raw numbers, includes source attribution and parent trend context, and discloses the $0.50/search price. 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 slightly longer than minimal but well-structured and front-loaded. Every sentence adds value: purpose, content type, alternative, scope, use case, and price. 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 no output schema, the description adequately hints at return values (quotes, interpretations, source attribution, parent trend context) and covers when to use the tool. It does not mention pagination or result limits, but the schema provides the 'limit' parameter. Overall, it is sufficient for a read-only search tool.

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

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

Schema description coverage is 100%, so all parameters are documented in the input schema. The description reinforces the narrative vs statistics distinction (also present in the types param description) but does not add new parameter-level details 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 it returns NARRATIVE-only qualitative evidence (expert quotes, editorial analysis, strategic perspectives) with source attribution and parent trend context, explicitly contrasting with search_statistics for hard numbers. This distinguishes it from sibling tools with a specific verb+resource+scope.

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?

It explicitly directs users to search_statistics for hard data points, market sizes, and growth rates, and recommends this tool when needing authoritative voices, strategic framing, or analytical depth that web search cannot provide. It also notes it works on all graphs, offering clear 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?

Beyond the readOnlyHint and destructiveHint annotations, the description adds that each result links back to an expert trend, works across all graph types, and costs $0.50 per search. These details help the agent understand cost and output linkage that annotations do not convey.

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 brief, information-dense paragraph with no fluff. It front-loads the core purpose ('HARD NUMBERS only'), then provides usage guidance, alternatives, scope, and pricing in a logical order.

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 absence of an output schema, the description adequately conveys the return type (quantitative data points) and the linkage to expert trends. It also covers usage context, alternatives, graph scope, and cost. It could be slightly more explicit about result structure, but overall is complete for a search tool.

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

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

The input schema already provides descriptions for all six parameters, so the description's additional context is minimal. It reinforces that graph_id works on all graphs and suggests multi-graph searching, but this mostly duplicates schema guidance.

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

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

The description explicitly states it returns hard quantitative data points (figures, market sizes, growth rates) and distinguishes it from search_insights which covers narrative content. The phrase 'HARD NUMBERS only' and the mention of working across all graphs leave little ambiguity about its function.

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?

It provides explicit guidance to use this tool when a question asks for a number or statistic, and to try it before supplemental data tools. It also names search_insights as the alternative for quotes and analysis, and advises searching multiple graphs for best coverage.

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