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

Annotations declare the safety profile (non-read-only, non-idempotent, non-destructive), and the description adds genuine behavioral context by revealing a multi-stage orchestration: credential verification, step retrieval, then guided profile creation. It does not specify failure modes or side effects of credential verification, keeping it short of 5.

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?

A single front-loaded sentence that names the action and enumerates the three sub-steps. Efficient with no filler, though the trailing clause list is slightly dense.

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?

There is no output schema, and the description never says what the caller receives (onboarding steps? a status object?) or what to do if onboarding was already begun. For a kickoff tool in a flow with siblings like get_onboarding_status and finalize_byo_mcp_onboarding, this leaves a real gap.

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

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

Schema coverage is 100% and both parameters (byoMcp, userId) are fully documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 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?

States a specific verb and resource ('Begin the Fodda expert onboarding process to create an authorized Human Agent') and names the concrete outcome. It is differentiable from siblings like submit_basic_info or finalize_byo_mcp_onboarding, though it does not explicitly contrast itself with them.

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 word 'Begin' implies this is the entry point of a flow, so usage is hinted at. But there is no explicit when/when-not guidance, no note that get_onboarding_status exists for resuming/checking, and no prerequisites such as being an authenticated expert.

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 carry the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real context beyond them: the traversal-based discovery mechanism and the shape of the result ('structured brainstorm map with territories'). It stops short of explaining depth tradeoffs or how many territories/connections come back, which with no output schema would have been valuable.

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, front-loaded with purpose, then differentiation, then usage, then return. Zero filler, though the final return sentence is slightly vague relative to how much space it takes.

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?

Read-only, three-parameter, no output schema and no nested objects, so complexity is low and annotations plus a full-coverage schema carry most of the load. The description is complete enough to invoke correctly; the only real gap is a slightly under-specified account of what the returned brainstorm map contains.

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%: depth, query, and userId all carry their own descriptions including depth's 1-vs-2 semantics and default. The description adds no parameter-level detail beyond that, so the baseline 3 for a fully documented schema is correct.

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?

States a specific verb+resource (explore/brainstorm a topic) and explicitly frames the mechanism (knowledge graph connections) and output (structured brainstorm map with territories). It also differentiates from the 'search' sibling by contrasting 'finds what matches' with 'discovers what CONNECTS', so an agent can route without opening schemas.

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 when-to-use triggers are listed ('brainstorm, explore adjacencies, find inspiration, or understand the landscape') and it names the alternative (search) with the condition that distinguishes them. This is close to the ideal when/when-not/alternative pattern, with only the near-neighbor discover_adjacent_trends left unaddressed.

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, openWorldHint=true, and idempotentHint=false, so the safety and mutability profile is covered. The description adds the useful fact that results aggregate across 100+ graphs plus external sources, but says nothing about output shape, latency, or coverage limits that would go beyond the structured fields.

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?

A single sentence that is front-loaded with the usage trigger and packs the capability list efficiently with no filler. It could be marginally tighter, but it wastes nothing.

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 read-only, 8-parameter intelligence tool with no output schema, the definition covers what the tool does but not what the caller receives or how the audiences enumerated in the trigger map to the returned artifacts. Given the annotations carry the safety profile and the schema carries parameters, this is adequate but leaves clear gaps.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters including format modes, graph_ids, and evidence limits. The description contributes no additional parameter meaning, which is the expected baseline when 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?

The description names a specific activity (auditing brand health, competitive footprint, trend associations, market momentum) and the data sources it draws on (100+ graphs, Google Trends, Wikipedia pageviews), which conveys what the tool produces. It does not, however, explicitly contrast itself with nearby siblings such as get_domain_intelligence, get_intelligence_dossier, or verify_market_claim, leaving the agent to infer the boundary.

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 'Use when auditing...' clause functions as an explicit usage trigger, which is better than generic guidance. But it names no alternatives and gives no when-not conditions, so an agent cannot tell when a sibling like get_domain_intelligence would be the better pick for an overlapping brand question.

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 cover read-only/idempotent safety, so the bar is lower. The description adds real value beyond that: polling cost (free), expected duration (a few minutes), recommended cadence, and the possible status values with artifact links on completion.

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?

Front-loaded purpose, then parameter sourcing, then return behavior and cadence, closing with a short parenthetical label. Every sentence carries usable information with no padding.

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?

Although no output schema exists, the description enumerates the return contract (status enum plus artifact links on completion) and the polling behavior, so an agent can act without further inference.

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's guidance ('Pass the job_id from that response') duplicates what the schema already states for job_id. No additional syntax or format detail is added, so the 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 states a specific verb+resource ('Poll a deliverable') and immediately names the sibling that produces the job_id ('commissioned with request_deliverable'). This clearly separates it from other status-check siblings like check_research_status and check_supplemental_status.

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 says when to use it (after commissioning via request_deliverable) and gives operational cadence ('poll every ~15–30s'), plus the fact that polling is free. It stops short of stating when not to use it, but the contextual routing 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 read-only, idempotent, non-destructive, and closed-world. The description adds valuable behavioral context: polling interval, terminal statuses, and that it retrieves a final report. It does not mention auth requirements or rate limits beyond the polling suggestion.

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 purpose, then usage, and is generally efficient. The parenthetical '(Async research job status poll.)' is slightly redundant but does reinforce the async nature without wasting much space.

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 polling tool with full schema coverage and rich annotations, the description provides clear cadence and terminal states. It could specify what the return looks like when not complete, but with no output schema, this is a minor gap.

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

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

Schema coverage is 100% and the single parameter 'job_id' is fully documented in the schema, including its sources. The description adds no additional parameter semantics beyond confirming the tool is used after deep_research_topic. Baseline 3 is appropriate when 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?

The description states a specific verb and resource: check deep research completion and retrieve the final report. It explicitly ties the tool to deep_research_topic, distinguishing it from the initiation sibling. However, it does not explicitly differentiate from other status-check siblings like check_deliverable_status or check_supplemental_status.

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 clearly says to call this after deep_research_topic and provides polling frequency (every 10 seconds) and terminal conditions (until COMPLETE or FAILED). No when-not scenarios or alternative tools are mentioned, so it falls short of a full 5.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds what annotations cannot: the async polling loop, the cadence, and the terminal states COMPLETE/FAILED. It does not say what the response contains beyond "results", but the behavioral workflow is well disclosed.

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?

Front-loaded with the core purpose, then sequencing, then cadence. Efficient overall; the trailing parenthetical "(Async supplemental query status poll.)" is slightly redundant with the first sentence but harmless.

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

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

No output schema exists, so the description must carry return-value burden; it says results are retrieved on COMPLETE and that FAILED is possible, which covers the essential lifecycle. It stops short of describing the result shape or what to do on FAILED, leaving a modest gap.

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

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

Schema coverage is 100% and the schema itself already states job_id is "The Job ID returned by get_supplemental_context". The description repeats that linkage ("Call this after get_supplemental_context") without adding format, validation, or failure-mode detail, so baseline 3 is correct.

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?

States a specific verb (check/retrieve) and resource (supplemental market data gathering results), and explicitly distinguishes itself from get_supplemental_context by naming that sibling as the prerequisite. An agent can tell this is the polling/completion leg of an async workflow.

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 sequencing ("Call this after get_supplemental_context"), explicit cadence ("poll every 5-10 seconds"), and explicit termination condition ("until status is COMPLETE or FAILED"). This is about as prescriptive as usage guidance gets.

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=false, destructiveHint=false, and idempotentHint=false, so the mutation profile is partly covered. The description usefully adds that confirming triggers questionnaire generation and that flagged findings can be attached, but says nothing about reversibility, permissions, or what confirmation commits to.

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 with the primary action and outcome front-loaded, followed by optional-parameter context. No filler, though the second sentence is slightly dense.

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?

There is no output schema, so return values need not be explained, but the description omits sequencing/prerequisites in what appears to be a multi-step onboarding flow (detect themes -> confirm -> interview). Adequate but leaves workflow position ambiguous.

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 schema fully documents all four parameters. The description only adds a conditional usage note for flaggedFindingIds/flagNote ('if the expert flagged any research findings as wrong or not theirs'), which is close to what the schema already states – so the baseline 3 holds.

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?

States a specific verb (confirm) plus resource (themes) and the downstream outcome (generating a tailored interview questionnaire). This clearly separates it from siblings like get_detected_themes or schedule_interview, though it never names an alternative explicitly.

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 implies the workflow role – confirm themes so the questionnaire can be generated for the audio interview – but gives no explicit when-to-use/when-not or prerequisite (e.g. that themes must first be detected/selected). Usage must be inferred from context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that — it doesn't explain the non-idempotent nature implied by idempotentHint=false, the conversational session behavior, or rate/latency traits. With annotations carrying safety, this is minimum viable.

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, zero waste, with the primary scope front-loaded and the alternative-parenthetical second. Every clause carries routing 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?

Purpose, alternatives, and parameter meaning are all covered by description plus schema, and no output schema means return values needn't be explained (the schema itself references the response's display name and session_id). It stops short of explaining what an engagement yields or the non-idempotent behavior, a minor gap for a read-only consult 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 the schema already documents all six parameters including deep, session_id, company, and analyst_id. The description adds no parameter-level meaning (e.g., how analyst_id relates to the entity types it describes), so the baseline 3 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?

States the specific verb (consulting) and the resources: synthetic domain analysts, C-Suite executive personas, and classic historical thinkers grounded in specialist knowledge graphs. It also names the sibling it is not for (living practitioners → consult_human_agent / request_expert_intro), so an agent can route without opening any schema.

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 frames the when-to-use case (synthetic/historical analysts) and the when-not case (living practitioners), naming two concrete alternatives. The exclusion plus the named alternatives leave nothing to inference.

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=false, and nothing in the description contradicts them. The description adds useful behavior beyond the annotations: session continuity via session_id, the deep-homework trigger semantics, and the cited-insights/next_moves return shape. It omits any auth, cost, or latency characteristics for a tool that spawns human work.

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?

Front-loaded with the triggering condition, which is good, but the middle sentences lean on marketing abstraction ('practitioner depth, proprietary frameworks', 'verified real-world expertise and published thinking') that adds little selectable signal for an agent. The useful operative facts (deep mode, return shape) are buried at the end.

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 does discharge the return-value burden by naming 'cited insights and next_moves', and all six parameters are schema-documented. The one real hole is sibling differentiation from consult_analyst, which the description never addresses despite that being the primary invocation risk.

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 every one of the six parameters is already documented in the schema, including 'deep', 'session_id', and the analyst_id routing/never-expose-raw-IDs rule. The description only restates 'Supports deep homework mode (deep: true)' and adds no syntax, defaults, or edge-case meaning beyond the schema, so the baseline 3 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?

States a specific verb+resource ('consulting an ... Human Agent') and enumerates the value it produces (practitioner depth, proprietary frameworks, strategic guidance; cited insights and next_moves). It never names or distinguishes itself from the obvious sibling consult_analyst, so an agent must infer the split from the name alone.

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 opening 'Use when consulting an authorized living Human Agent' plus the 'On-Request Human Agents undergoing onboarding' clause gives a partial when-to-use condition. However, there is no explicit when-not guidance and no mention of the near-identical 'consult_analyst' sibling or 'find_expert'/'list_analysts' as the upstream discovery path (those appear only inside a parameter description).

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=false and destructiveHint=false, so the safety profile is covered. The description usefully adds that execution is 'autonomous' and 'multi-pass', hinting at a long-running unattended process. It omits latency/duration expectations and any async polling cue (notably absent despite a check_research_status sibling), so it adds modest value only.

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?

A single front-loaded sentence that opens with the trigger ('Use when...') and packs the output type and scope with zero filler. Nothing is redundant and the most decision-relevant information leads.

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 6-parameter tool with full schema coverage and safety annotations, the description covers the what and when adequately. It does not signal the likely long-running/async nature of an autonomous multi-pass job, which an agent needs in order to call it correctly. With no output schema, a brief note on what is returned (beyond 'briefing report') would have closed the gap.

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

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

Schema description coverage is 100%, so query, mode, depth, sub_themes, userId and graphId are all already documented in the schema with enums and usage notes. The description contributes no additional parameter guidance, so the 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?

States a concrete deliverable (an 'exhaustive, autonomous multi-pass briefing report') and its ingredient sources (cross-graph trends, corporate disclosures, expert perspectives), which is far more specific than a bare 'research' verb. It implicitly separates itself from lighter siblings like brainstorm_topic or search_graph. It stops short of naming the alternatives it is not, so it lands at 4.

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 whole description is a single use-condition ('Use when the user needs an exhaustive... report'), which gives a clear trigger. However, it offers no exclusions, no prerequisites, and does not route the agent away from cheaper siblings such as brainstorm_topic or discover_adjacent_trends. Usage is implied rather than fully specified.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the pipeline of embedding fetch, cosine-distance query, and especially the 'direct link exclusion filter', which tells the agent that directly connected trends are deliberately omitted and results are non-obvious. It still omits return format, ordering, and cost/rate behavior.

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

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

Two sentences, front-loaded with the purpose before the parenthetical mechanics, with no filler. The internal-pipeline parenthetical is terse and slightly jargon-heavy, but it is compact rather than padded.

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 read-only discovery tool with 8 fully documented parameters and no output schema, the safety profile and parameter meanings are adequately covered by annotations and schema. However, the description says nothing about how many/how results come back, how min_score interacts with limit, or the trial-tracking userId behavior, leaving meaningful gaps for an 8-parameter 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 the schema already explains limit, query, seed_query, trend_id, min_score, and the rest. The description only loosely gestures at the seed-embedding step and adds no syntax, format, or precedence guidance (e.g. seed_query vs trend_id vs query) beyond what the schema provides. Baseline 3 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 names a concrete operation (vector-similarity graph traversal) and a concrete resource (adjacent, cross-domain trend patterns), so the agent knows it returns trends rather than nodes or claims. It does not, however, differentiate itself from siblings like get_neighbors or search_graph, which could plausibly surface similar-looking output. Clear verb+resource, but no sibling routing.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The agent must infer from the schema (seed_query vs trend_id) how to invoke it, but nothing tells it why it would pick this over search_graph, get_neighbors, or get_validated_trends.

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 the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false, idempotentHint=false). The description then adds genuinely useful behavior beyond that: billing model ('bills as one content call'), free 24h caching, and crucially that it returns an EVIDENCE PACK plus a composition contract and that YOU write the article (including the methodology box). It doesn't detail the evidence-pack structure, but the added operational context is substantial.

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?

Front-loads the core purpose and word count before routing triggers and mechanics. Efficient overall, though the trailing parenthetical '(Deep trend evidence extraction + multi-section outline + longform article drafting.)' is somewhat redundant with earlier text.

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

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

For a complex, multi-stage generation tool with no output schema, the description is nearly complete: it explains the deliverable (evidence pack + contract), the division of labor (agent writes the article), billing, and caching. Minor gaps remain around the exact shape of the returned evidence pack.

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 7 parameters (including the brand earnings-truth layer, sub_themes rationale, and target_length ±20% contract). The description reinforces the sub-themes and thesis-pressure-test concepts but adds little parameter-level syntax beyond what the schema states, so the baseline of 3 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?

States a specific verb+resource (draft a LinkedIn ARTICLE), a concrete scope (800–1,200 words), and the grounding source (Fodda knowledge graphs). It explicitly differentiates from its closest sibling by noting it 'Runs a broader evidence sweep than the post tool,' so an agent can tell it apart from draft_linkedin_post without opening either schema.

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 trigger phrases ('turn this research into an article…', 'write a LinkedIn article about…') and a use-case condition (long-form thought leadership). The comparison to the post tool gives a clear when-to-use-this-vs-alternative signal.

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 only cover safety/idempotency), it discloses the return contract (curated EVIDENCE PACK with typed sources and never-constructed URLs), honesty behavior (thin coverage flagged, dropped themes logged), and billing semantics (one content call; identical re-requests within 24h served from cache free). This is rich operational context an agent cannot get from 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?

Purpose is front-loaded and sentences are dense with useful detail (triggers, return format, billing). It is somewhat long and packs multiple concerns (caching, billing, sub-operations parenthetical) that could be trimmed, but nothing is clearly wasteful.

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 carries the return-format burden and does so fully: evidence pack structure, composition contract, coverage honesty, caching and billing. An agent knows what it gets back and how it is charged before calling.

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% and the parameter descriptions (brand's earnings truth layer, voice enum, SPECIFIC sub_themes guidance) are already detailed. The description adds no per-parameter meaning beyond the schema, so the baseline of 3 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 names a specific verb (Draft) and resource (LinkedIn post) and scopes it to 'any topic, grounded in Fodda's expert knowledge graphs'. It also clarifies the division of labor ('YOU write the post' from the returned evidence pack), which distinguishes it from a plain generation 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?

It gives concrete trigger phrases ('draft a LinkedIn post about…', 'write a post on…', 'turn this into a LinkedIn post') and states the context (social content backed by receipts). It does not, however, name the sibling draft_linkedin_article or state when to prefer one over the other, so it stops short of fully explicit alternative routing.

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 the non-read-only, non-idempotent, non-destructive profile, so the safety burden is partly covered. The description adds genuinely useful behavior beyond that: the job runs asynchronously for 1-2 minutes and the caller must not block on it. It does not say how or when results become available.

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 short sentences, front-loaded with the action and scope, then the async timing, then the immediate next step. No filler; every sentence changes agent behavior.

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 fire-and-forget async trigger with no output schema and a single fully documented parameter, the description covers everything needed to invoke it correctly and what to do next. The one omission is how the agent later retrieves the research results, which a polling sibling likely handles.

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% for the single optional 'userId' parameter, so the schema already carries the semantics. The description adds nothing about the parameter, which is acceptable when coverage is complete but earns only the 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?

States a specific verb ('Initiate background research') and a specific resource (the expert's public work and domain insights), plus the downstream purpose (expertise and voice modeling). It is distinguishable from siblings like deep_research_topic or check_research_status, though it does not name them explicitly.

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?

Gives clear usage context: run this, do not wait, proceed to the Tone of Voice study in chat. The 'do NOT wait' instruction removes ambiguity about blocking behavior. It stops short of naming the sibling used to poll results (e.g., check_research_status).

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=false, idempotentHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: it creates an Airtable record and implies a terms-acceptance gate. It doesn't state whether re-invocation is safe or what happens on partial failure, but with annotations covering non-destructiveness, 3 is fair.

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 the primary action, no filler. The middle mention of profile-save-on-terms-acceptance is slightly compressed but earns its place by flagging a gating condition.

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 non-idempotent mutation with no output schema, the description covers purpose, side effect, and a terms gate, but omits prerequisites relative to the other onboarding steps and result/error behavior. It is adequate but leaves the ordering questions a caller of the final step would need.

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 12 parameters are already documented in the schema; baseline is 3. The description mentions terms acceptance and MCP details but adds no format or constraint detail 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?

States a specific verb and resource: 'Finalize ... onboarding and submit the profile for review', plus the concrete side effect of creating a Human Agent record in Airtable. It is distinguishable from siblings like submit_mcp_source or confirm_themes, though it doesn't explicitly name where it sits in the sequence relative to them.

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?

Implies this is the last step ('finalize... submit for review here'), which gives positional context. However, it never states prerequisites (e.g. that basic info, MCP source, and confirmed themes must already be submitted) or what to do if a step is missing, which for an ordered onboarding flow is the key usage question.

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 destructiveHint=false, so safety is covered. The description adds valuable non-annotation context: the return shape (action lines, credibility anchors, why matched), the roster breadth (4,150+), and the two-tier agent distinction with the correct follow-up tool for each. It stops short of explaining ranking or reliability caveats.

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 trigger condition before the return description, so the agent learns when-to-use first. The second sentence is dense with parenthetical asides but every clause carries routing or return information, so little waste.

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

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

No output schema exists, so the description carries the burden and does: it explains the number of results, their contents, the roster scale, and how to act on each agent tier via named sibling tools. Nothing essential for calling this discovery tool correctly is missing.

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 three parameters (query, limit, userId) are already documented; baseline 3 applies. The description only loosely reinforces the query intent and the 2–3 result count, adding no syntax or format detail 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?

States a specific verb+resource (find expert) and frames it as a discovery/ranking operation via the 'Returns 2–3 ranked candidate experts' clause. It explicitly distinguishes itself from the sibling consult_human_agent (consultation) and request_expert_intro (introduction), so an agent can tell it apart without opening schemas.

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?

Opens with an explicit 'Use when the user asks what specialists think, seeks an authoritative perspective, or needs practitioner depth' and supplies two concrete example phrasings. It also routes follow-up actions: consult_human_agent for active agents vs request_expert_intro for on-request agents, 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?

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds valuable non-annotation context: it returns a branded SVG that renders directly in chat and performs data payload transformation plus SVG rendering. It stops short of noting rate limits or auth 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?

Front-loaded with purpose, then a compact chart-type catalog, then the return value. Every clause earns its place; the trailing parenthetical about internal mechanics is the only slightly redundant element.

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 two fully-documented required parameters and no output schema, the description supplies the missing return-value information (SVG rendered in chat) and the chart-type semantics. It lacks only edge-case guidance (e.g., malformed data handling).

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

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

Schema coverage is 100% (baseline 3), but the description adds meaning beyond the raw enum by explaining what each chart_type represents (From→To transitions, 2×2 white space, etc.), which directly helps the agent pick a value and shape the data payload.

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?

States a specific verb+resource ('Create a presentation-ready data visualization from research findings') and then enumerates all six supported chart types with one-line semantic glosses. No sibling tool offers visualization, so an agent can immediately place 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?

The phrase 'from research findings' implies the context in which to reach for it, and the chart-type glossary helps select the right variant. However, it never states when to use this versus siblings or any prerequisites/exclusions, leaving usage to inference.

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, so the safety profile is fully covered structurally. The description adds only that the operation is free ('pricing catalogue read (free)'), a small but real addition beyond the annotations.

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

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

Two sentences, front-loaded with the return contents before the usage trigger. The trailing parenthetical is slightly awkward stylistically but carries the useful 'free' detail, so it 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 no output schema, the description correctly enumerates what comes back (capabilities, offerings, expert mechanics, pricing) so an agent knows what to expect. It is essentially complete for a free read; only the exact response shape remains unspecified.

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% — both 'topic' and 'userId' are documented in the schema, including the topic-reconnaissance behavior and the omit-to-get-overview default. The description does not add parameter detail, so the baseline 3 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?

Specifies a concrete verb (Returns) and enumerates the exact resources covered: capabilities, offerings, Human Agent mechanics, expert recruitment/onboarding, and pricing. It clearly reads as the platform catalogue tool and is easy to distinguish from action-oriented siblings like find_expert or consult_analyst.

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?

Gives explicit invocation triggers ('Call this for any question about what Fodda can do, how experts work, what's available, or how much something costs'), which is strong when-to-use guidance. It does not name an alternative tool or state exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/openWorld and non-destructive, so the safety profile is covered. The description adds genuine behavioral context: coverage is limited to 517 consumer-sector tickers and uncovered tickers fall back to web-backfill, which warns the agent that result provenance and completeness vary. It stops short of rate-limit or latency details, but for a read tool this is solid.

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?

Front-loaded with the identity of the tool, then contents, coverage/fallback, and routing guidance in a tight sequence. Every sentence carries signal, though the parenthetical list and Fodda provenance reference make it slightly dense.

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

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

No output schema exists, so the description usefully summarizes what the record returns and its coverage/fallback behavior, which is the critical context. For a nine-parameter tool the individual modes are left to the schema, which fully covers them, keeping this near-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 description coverage is 100%, so all nine parameters (including the mode/view enums and required-for relations) are already documented in the schema. The description adds no parameter-level guidance, so the baseline of 3 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?

States a specific resource (per-ticker earnings) with clear scope ('canonical per-ticker earnings source') and enumerates what the record contains (analyst concerns, sentiment, activity, CEO intelligence, validated trends). It explicitly differentiates itself from the sibling get_earnings_intelligence, so an agent can route without opening either schema.

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?

'Use this for company-specific data. Use get_earnings_intelligence for cross-company thematic comparisons' gives explicit when-to-use and names the alternative with the discriminating condition. Nothing is left to inference for 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral fact that this surfaces verified research findings ahead of themes, but says nothing about return format or ordering. Baseline for annotation-covered reads is appropriate here.

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, but the second is a semicolon-joined run-on mixing a description of returned content with an instruction about confirming themes. The core action is front-loaded adequately, but the second sentence could be split or 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?

For a read-only, single-optional-param tool with annotations covering safety and no output schema, the description covers the workflow role adequately. It could say more about what a 'theme' or 'finding' object contains, but the absence of an output schema lowers the burden.

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% and there is a single optional userId param already documented as 'Optional user identifier.' The description adds no syntax or meaning beyond the schema, so the baseline 3 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?

States a specific verb ('Fetch') and resource ('detected themes derived from the expertise analysis and background research') and clarifies the object of the operation. It distinguishes itself from confirm_themes by positioning this as the review step that precedes confirmation, though it doesn't name the sibling explicitly.

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?

Gives clear workflow context: use this for expert review, ask the expert whether findings are wrong or not theirs *before* asking them to confirm themes. This sequences it relative to confirm_themes. No explicit 'when-not' exclusion, but the condition that selects it is well conveyed.

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 openWorldHint=false, so the safety profile is clear. The description adds real behavioral value beyond that: no graph ID is required, all seven graphs are queried in parallel, and results come back as editorially structured trends with bundled evidence and source attribution. It stops short of covering pagination, result freshness, or ranking behavior.

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

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

Front-loaded with the core action and scope, then progressively adds routing rules. It is dense with useful content, but the 'bundled evidence' idea is stated twice (first and third sentences), which is a minor 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?

No output schema exists, so the description carries the return-value burden and does it well, describing trends plus bundled evidence types (case studies, statistics, quotes, analysis with attribution). All parameters are documented in the schema, and routing to the relevant siblings is covered, leaving nothing an agent needs missing.

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% and each of the six parameters (limit, query, userId, min_score, include_evidence, max_evidence_per_trend) already carries its own description with defaults and caps. The description clarifies the evidence-bundling behavior that include_evidence controls, but adds no syntax or format detail beyond the schema, so the baseline of 3 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?

States a specific verb (Search) and resource (PSFK-curated domain graphs), enumerates the seven covered domains, and names the scope ('searches all 7 live domain graphs in parallel'). It also distinguishes itself from web search and from the brand_tracker sibling, so an agent can select it without opening any schema.

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 routing rules: use brand_tracker when the query names a company/brand, use get_supplemental_context for city-level or regional sub-cuts, and it is preferred over web search for trend-level intelligence. Both when-to-use and when-to-use-something-else are stated.

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=false, and destructiveHint=false, so the safety profile is partially known. The description adds that the tool performs reads from two Airtable tables and a sentiment gap calculation, which is useful operational context. However, it does not disclose whether the operation is expensive, whether it caches results, or what the idempotency=false means in practice.

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 two sentences, but the second sentence is a parenthetical list of internal steps that reads like implementation notes rather than front-loaded value. It is not overly wordy, but the structure could be improved by leading with the core output and keeping the technical details secondary.

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 and 7 optional parameters, the description gives a high-level idea of what is computed but does not explain what the output looks like (e.g., themes, deflection counts, scores). It is adequate but leaves gaps that an agent would need to infer.

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

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

Schema coverage is 100%, so all 7 parameters are fully described in the schema. The description adds no parameter-level detail beyond what is in the schema; it simply notes the data sources involved. Baseline 3 is appropriate when 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?

The description states a specific analytical purpose ('comparing analyst line of questioning against executive management prepared remarks'), which is clearer than a tautology. However, it is dense with internal jargon ('Truth-layer analysis', 'divergence matrix') and does not clearly distinguish this tool from siblings like get_earnings_intelligence or get_company_earnings. An agent might struggle to know when exactly to pick this over those.

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?

There is no explicit guidance on when to use this tool versus the many other earnings-related siblings (get_earnings_intelligence, get_company_earnings, get_my_earnings). The description implies a specific use case but offers no routing cues, prerequisites, or exclusions.

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

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

Annotations already disclose readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: provenance tags ('knowledge_graph' or 'web_supplemental'), the confirmed_absent brands behavior on multi-company queries, and server-side intent routing to avoid conflation—all useful and non-obvious.

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?

Information-dense and largely front-loaded, with the primary purpose first and routing/examples after. It is long, but nearly every sentence carries distinct routing or semantic value, so little is wasted.

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?

Although there is no output schema, the description explains what results contain (active initiatives plus confirmed_absent brands, provenance tags), which is exactly what an agent needs to interpret a call. Nothing essential is missing for a 10-parameter, zero-required 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?

With 100% schema coverage the baseline is 3, but the description adds genuine meaning: it explains the activity enum's 'sustainability' semantics and warns about conflation with analyst margin-sustainability questions, and it gives search-term examples ('labor costs', 'tariff guidance'). This goes beyond the schema text.

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?

States a specific verb+resource ('cross-company thematic earnings intelligence from the knowledge graph and web sources') and immediately differentiates itself from siblings by naming the use cases it owns vs. those that belong to get_company_earnings and brand_tracker. An agent can route without reading either schema.

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 enumerates when to use it (multi-company comparisons, industry-level, sector filters, activity categories) and names two alternatives with the conditions that select them: 'For single-brand earnings, brand_tracker…' and 'For per-ticker structured analysis… use get_company_earnings.' This is near-ideal routing 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, idempotentHint, destructiveHint=false, and the closed-world openWorldHint=false, so the safety profile is covered. The description adds useful return-content context (trends, signal scores, cited URLs), but says nothing about auth, rate limits, or that a node lookup is a prerequisite.

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?

A single dense sentence with the retrieval action and its return payload front-loaded. No redundant or filler clauses; every phrase contributes.

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?

There is no output schema, so the description partially compensates by naming the returned fields (trends, signal scores, citations). But it omits the two-step workflow (search_graph → get_evidence) and any pagination/top_k behavior, leaving the agent to infer the calling context.

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 four parameters are already documented in the schema, including the critical warning that for_node_id must come from a prior search result. The description adds no parameter meaning beyond that baseline, which is the expected 3 when 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?

Names a specific verb and resource (semantic search across knowledge graphs) and qualifies the output (top trends, signal scores, publisher citations with source URLs). However, it does not distinguish itself from the sibling search_graph, which the sibling name alone suggests competes for the same 'search' intent.

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 no when-to-use or when-not-to-use guidance. It never states that this tool is a follow-up to search_graph or that a prior node result is required — that flow is only discoverable by reading the schema's for_node_id description.

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 disclose readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description does add non-obvious operational context (1 registry lookup + 8 parallel Cypher queries + 1 merge pass), which hints at fan-out cost and latency. However, it omits the behavioral fact that actually matters for selection: that this is a legacy alias of get_specialist_intelligence.

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 compact sentences with the primary capability front-loaded and no filler. The parenthetical pipeline detail is borderline noise for an agent choosing a tool, but it is short and does not obscure the main clause.

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 six-parameter search tool with no output schema, the description should at least explain what comes back conceptually (trends, evidence bundles) and warn that it is a legacy alias. It does neither, and the annotation-only signal about aliasing would be invisible to an agent reading the description 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 description coverage is 100% with all six parameters (query, limit, min_score, include_evidence, max_evidence_per_trend, userId) documented in the schema itself. The description adds no parameter-level detail such as query syntax expectations or how min_score interacts with limit, so the baseline of 3 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 states a recognizable action ('parallel search across ... frameworks and ... specialist strategist graphs'), but the vocabulary ('strategist agency frameworks', 'specialist strategist graphs') does not match the tool name ('expert') or the annotation title ('Specialist Intelligence'), leaving the actual resource ambiguous. It also never distinguishes itself from the sibling tool 'get_specialist_intelligence', which the annotations imply it aliases.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_specialist_intelligence, search_graph, or get_domain_intelligence. Since the annotation title labels this a 'Legacy Alias', the absence of any routing note to the canonical tool is a meaningful omission.

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 cover the safety profile (readOnly, openWorld, non-destructive, non-idempotent), so the description earns credit for adding what they don't: a $0.50 cost, the specific external source classes synthesized, adversarial testing, and an optional editorial segment. It still omits latency and why the operation is non-idempotent.

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 the core action and scope, then the source composition, then the optional add-on and price. Every clause carries information and nothing is repeated from the 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?

With no output schema, the description usefully enumerates what the dossier contains (case studies, reports, quotes, macro metrics, adversarial testing) and discloses cost. It stops short of describing return structure, size, or turnaround expectations for what is a heavy multi-source aggregation call.

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 topic, sector, userId, tickers, and include_editorial. The description hints at 'emerging theme' for topic and the PSFK briefing for include_editorial but adds no syntax, format, or constraint detail beyond the schema; baseline 3 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?

States a specific verb ('Assembles') and resource ('certified multi-source Evidence Dossier') with clear scope ('any market topic or emerging theme in a single call'). An agent can tell what it produces, though it never names or contrasts against siblings like deep_research_topic or get_domain_intelligence.

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

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

No explicit when-to-use or when-not guidance, and no alternative tool is mentioned despite many overlapping siblings (get_evidence, deep_research_topic, get_domain_intelligence). 'In a single call' faintly implies an aggregation/efficiency tradeoff but leaves the routing decision to inference.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is low; the description still adds meaningful behavior by noting that label="Trend" returns the full deterministic list whereas search may return partial results. It omits return shape and rate/pagination behavior, but the determinism disclosure is the key operational trait.

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?

Purpose and the Trend special case are front-loaded and the example queries earn their space, but the trailing parenthetical '(Graph taxonomy label value lookup.)' repeats information already stated in the first sentence.

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 4 parameters all fully documented in the schema, no output schema, and annotations covering safety, the description supplies enough context to call the tool correctly. Minor gaps remain around return format, which the absence of an output schema leaves unaddressed.

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, but the description adds value beyond the schema by showing how the 'label' parameter selects the value set and by singling out label="Trend" as the deterministic full-list case, plus giving free-text example labels.

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?

States a specific verb and resource ('List all brands, locations, technologies, audiences, or trends within a specific knowledge graph') and clarifies it is a taxonomy value lookup, so an agent can distinguish it from search_graph and get_node without opening a schema.

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?

Gives clear triggering conditions with concrete example queries ('what brands are in the retail graph?') and a specific when-to-use case for label="Trend" where search may return partial results. It does not name the alternative sibling tools explicitly, but the alternative behavior (search) is described.

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, non-destructive, and openWorldHint=false. The description adds a genuinely useful behavioral trait beyond them: 'Returns live data — not cached from session start,' telling the agent the result is fresh rather than session-stale.

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?

Front-loaded with the resource and returned fields, and the usage triggers come next. The trailing parenthetical '(User account status & credit balance lookup.)' largely restates what precedes it, a minor 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 no output schema, the description carries the return-value burden and does so by listing the four returned data categories. Auth/permission requirements are not stated, a small gap for an account-scoped tool, but overall the definition is sufficient 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?

Zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description's enumeration of returned fields compensates adequately for the absent output 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?

States a specific verb (check) and resource (current user's account), then enumerates exactly what is returned: API call balance, plan, enabled/disabled graphs, and profile info. This clearly distinguishes it from siblings like list_graphs, get_capabilities, and get_my_earnings.

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?

Gives concrete when-to-use triggers with sample user questions ('how many API calls do I have?', 'what plan am I on?'), which is strong routing guidance. It does not name alternative tools or exclusions, so it stops short of the 5 bar.

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, non-destructive, and closed-world, so safety is covered. The description adds no behavioral context beyond that: it doesn't say whether an expert account is required, what time window the earnings cover, what currency/units are returned, or how the optional userId changes the result.

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?

A single six-word sentence that is front-loaded and wastes nothing. It is brief rather than bloated, though the brevity shades into under-specification.

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 and only one loosely documented parameter, the description should do more work: it never defines 'Fodda', never states the access requirement, and never describes what the returned earnings contain or over what period. An agent can guess the gist but cannot confidently call or interpret the result.

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

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

With 100% schema description coverage and one optional parameter, the schema carries the parameter burden, so the baseline of 3 applies. The description adds nothing about the optional userId and its 'my'/'the expert's' framing sits in slight tension with a parameter that lets you look up someone else.

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?

It gives a verb ("Check") and a resource ("the expert's Fodda earnings"), so the general intent is legible. But "Fodda earnings" is platform jargon that is never explained, and nothing distinguishes this from siblings like get_earnings_intelligence, get_company_earnings, or get_earnings_divergence.

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?

There is no when-to-use guidance, no prerequisites (e.g., must be an onboarded expert), and no mention of any alternative tool. The agent is left to infer that this is for the caller's own earnings purely from the tool name.

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=true, idempotent=true, destructive=false and openWorld=false, so the safety profile is covered. The description adds genuinely useful context beyond that: results are 'curated editorial connections', the underlying store is Neo4j, and it is a 1-hop traversal from the seed node.

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, front-loaded with the outcome and followed by usage and the structural note. Slightly dense and the parenthetical about Neo4j 1-hop traversal is somewhat redundant with the usage sentence, but there is no 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?

There is no output schema, so the description carries the burden of describing returns, and it does so adequately ('curated editorial connections'). Combined with the prerequisite and the traversal semantics, an agent has what it needs to call this correctly; only a note on result shape/size would push it higher.

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 every parameter is already documented in the schema, including depth/limit defaults and the direction semantics. The description only reiterates the node_id prerequisite, which the schema also states emphatically, so it adds little beyond the structured fields.

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 names a specific verb and resource ('Discover what's connected to a specific trend') and enumerates the kinds of results (related brands, technologies, locations, cross-domain links). It also distinguishes itself from the sibling search_graph by positioning itself as the follow-up relational traversal step, so an agent can tell them apart.

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 says to use it after search_graph and lists concrete intents (map territory, find connected brands, understand cross-domain relationships), plus a prerequisite (node_id from a prior search_graph result). It lacks explicit when-not-to-use guidance or named alternative tools beyond the prerequisite, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that this is a 'Direct Neo4j node metadata lookup by ID', implying a raw, non-enriched read, but says nothing about failure behavior for invalid IDs, cost, or limits.

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

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

Front-loaded with the payload contents, then usage, then the prerequisite. The trailing parenthetical on Neo4j is slightly awkward and could be folded in earlier, but every sentence carries 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?

With no output schema, the description usefully enumerates the return fields and the required input provenance, which is the main thing an agent needs. Remaining gaps (error handling for bad IDs, response shape details) are minor for a simple read-by-ID 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% and the nodeId/graphId descriptions already carry the critical warnings (non-sequential IDs, do not pass trend name, use list_graphs for graphId). The description only restates the node_id provenance requirement, so the schema does the heavy lifting; baseline 3 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?

States a specific verb and resource ('Get the full profile of a specific trend') and enumerates the returned fields (description, lifecycle stage, signal strength, geographic scope). It explicitly differentiates itself from the sibling search_graph by contrasting a summary with deep single-node detail.

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?

Gives an explicit trigger ('Use when you need deeper detail on a single trend after search_graph returned a summary') plus the prerequisite that node_id must come from a prior search_graph result. The alternative tool and the condition that selects it are both named, leaving nothing to inference.

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 this as a safe, idempotent, closed-world read. The description adds genuinely new behavioral context beyond that: waitForResearch blocks server-side for ~25s and returns early on completion/failure, and it tells the agent how to handle the next_action field (relay in its own words).

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 tight sentences, front-loaded with the core purpose, then the blocking-time caveat, then the output-handling instruction. No 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 no output schema, the description must carry return-value semantics, and it only documents next_action. Progress/status fields and what the response looks like otherwise are left unspecified, so the picture is partial for a status 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 userId, analystId, and waitForResearch are already documented. The description largely restates the waitForResearch schema text rather than adding format or precedence details, so baseline 3 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?

States a specific verb (check) and resource (expert onboarding progress/status), which is distinct from the many other 'check_*_status' siblings by virtue of the onboarding scope. It does not, however, explicitly contrast itself with begin_expert_onboarding or expert_onboarding_research, so the agent must infer the boundary.

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?

Usage is implied (call this to see where an expert is in onboarding) and the waitForResearch guidance implies a polling use case, but there is no explicit when-to-use/when-not or naming of the alternative tools that also report progress.

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=false, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context beyond that: the default output is 'an executive 5-pillar analyst briefing with cross-graph validation' and no graph ID is required. It stops short of rate-limit/auth detail, but with annotations carrying the rest a 4 is warranted.

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 purpose is front-loaded and each subsequent sentence carries routing or scope information, so most content earns its place. It is dense and slightly long, but there is little waste.

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 7-parameter tool with no output schema, the description covers purpose, alternatives, and the shape of the return (5-pillar briefing vs. raw structured records). An agent has enough to call it correctly, though a note on the non-idempotent/read behavior of repeated queries is absent.

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 7 parameters including the view enum, limit, and min_score defaults. The description adds only marginal parameter meaning (implying the editorial default mode and that no graph ID is needed). Baseline 3 is correct when 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?

States a specific verb and resource ('searches industry report knowledge graphs ... for published forecasts, projections, and whitepaper findings') and names the data sources. It explicitly differentiates itself from siblings get_domain_intelligence, search_statistics, and brand_tracker, so an agent can select it without opening any schema.

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-not guidance ('Does NOT return living consumer domain trends ... use get_domain_intelligence') and routes to the correct alternative for a specific condition ('When the query names a specific company or brand, brand_tracker is the entry point'). Nothing is left to inference.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds real behavioral context beyond that: a deprecation notice steering toward preferred tools, and the fact that no graph ID is required despite being a graph search. It does not address auth, rate limits, or pagination, so it stops short of a 5.

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 but well front-loaded: deprecation warning first, then purpose, then routing exclusions. Every clause carries routing or scope information, though the parenthetical list of curators is slightly ornamental and could be trimmed.

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

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

Given six parameters (one required), no output schema, and a crowded sibling set of similarly named intelligence tools (get_domain_intelligence, get_expert_intelligence, get_report_intelligence, search_graph), the description supplies everything needed to select and call it: scope, return type, exclusions, and named alternatives. Nothing further is required.

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 six parameters (limit, query, userId, min_score, include_evidence, max_evidence_per_trend) are already documented in the schema. The description adds only the 'No graph ID needed' detail, which clarifies an absent parameter rather than explaining existing ones. Baseline 3 applies when 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?

States a specific verb and resource ('searches specialist knowledge graphs curated by domain strategists, newsletters, and boutique studios') and names what it returns (specialist frameworks and analysis). It explicitly distinguishes itself from get_domain_intelligence, search_statistics, and brand_tracker, so an agent can route without opening any schema.

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?

Gives explicit alternatives with selection conditions: search_graph for topic-routed multi-graph searches, consult_human_agent/consult_analyst for direct strategist consultation, brand_tracker when a company/brand is named. It also states negative scope (not broad consumer trends, not standalone statistics), which is exactly the when-not guidance an agent needs.

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, and idempotentHint=false. The description adds useful latency/cost context by disclosing the cache check, 8 parallel outbound HTTP calls, and a categorization pass, which implies external fan-out and variable results. It stops short of stating return shape, rate limits, or failure behavior, so it earns moderate credit on top of the annotations.

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

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

Two sentences, front-loaded with sources, but the parenthetical about '1 memory cache check + 8 parallel outbound HTTP API calls + 1 5-bucket categorization pass' is implementation detail an agent cannot act on. It spends words on internal mechanics rather than on decision-relevant 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?

With no output schema and 6 parameters, the description should describe what comes back and in what form, but it says nothing about the return payload. Combined with missing usage guidance, it is not complete enough for an agent to invoke confidently despite annotations covering the safety profile.

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 alone fully documents all six parameters including the tricky 'domain' exclusion rule. The description adds no parameter-level detail, making the baseline 3 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 verb ('fan-out pulling') and resource ('real-time economic data from 80+ institutional sources') are stated concretely, so the mechanical operation is graspable. However, the purpose is framed around internal architecture rather than an agent-facing task, and it never clarifies what 'supplemental' context means or how it differs from siblings like get_domain_intelligence or search_statistics. That ambiguity keeps it at a vague-purpose 3.

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 contains no when-to-use, when-not-to-use, or alternative-selection guidance. Nothing tells the agent which query types should route here versus the many intelligence/search siblings. Only the parameter docs hint at usage, and those are not part of the description.

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, openWorldHint=false, and destructiveHint=false, so the safety and idempotency profile is covered. The description usefully adds provenance (earnings cross-validation by Fodda's pipeline) but says nothing about result volume, freshness, or pagination behavior; a 3 is appropriate with annotations doing the heavy lifting.

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 tight sentences, front-loaded with what is returned and followed by the data lineage. No filler, though the second sentence is somewhat redundant with the first.

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?

Parameters and safety annotations are fully covered, but with no output schema the description never sketches the shape of a returned trend, and it provides no routing against the dense set of trend-fetching siblings. Adequate but with clear gaps for a discovery tool in a crowded namespace.

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 all five parameters documented, so the baseline is 3. The description adds no syntax, format, or interaction detail beyond the schema (e.g., how limit and search combine), so it earns no lift.

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?

States a specific verb ('Returns') and resource ('market-validated consumer trends from corporate earnings reports'), and clarifies the cross-validation source. However, it does not distinguish itself from close siblings like get_detected_themes, discover_adjacent_trends, or get_earnings_intelligence, leaving the agent to infer boundaries.

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, and no prerequisites or exclusions. Given the many adjacent trend/earnings siblings, this omission is significant; the agent must guess which trend tool fits a given query.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds useful context that this is a "Fast analyst registry metadata lookup," signaling lightweight metadata return rather than full content, but it says nothing about pagination, fields returned, or auth.

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 purpose and usage are front-loaded, but the middle sentence ("unique voice, methodology... cannot be replicated by web search") is promotional filler that doesn't help an agent invoke the tool, and the trailing parenthetical is awkwardly placed after the usage instruction.

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 should carry more of the return-value burden; "registry metadata lookup" hints at the shape but never specifies what an analyst entry contains. For a zero-required-parameter list tool this is adequate but leaves a real gap.

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

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

Schema description coverage is 100%, so the query, userId, and category semantics (including the enum) are already fully documented. The description adds no parameter-level meaning beyond what the schema provides, which lands at the 3 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?

States a specific verb+resource ("List available Synthetic Analysts") and adds a disambiguating gloss ("named expert personas grounded in specific knowledge graphs"). However, it describes only synthetic analysts while the sibling annotation title ("List Human Agents, C-Suite & Analysts") and the category enum (human_agent, classic_agent, c_suite_agent) indicate the tool lists broader categories — a scope mismatch that slightly clouds what is actually returned.

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?

Gives a when-to-use trigger ("user asks to 'talk to' or 'consult' an expert, or when you need specialist depth"), but that trigger actually points at consult_analyst/consult_human_agent rather than a listing tool, and no alternative or exclusion is named. The guidance is implied rather than properly routed.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description adds value by disclosing which graph identifiers are deprecated (waldo, psfk) and what valid alternatives to use. It also hints at the call being a fast registry lookup. It stops short of noting result size or pagination behavior, so not a full 5.

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?

Front-loaded with the action and guidance, and the deprecated-identifier warning earns its place. The trailing parenthetical '(Fast graph registry metadata lookup.)' is redundant restatement of the opening clause and slightly dilutes an otherwise tight definition.

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 compensates by enumerating the returned metadata fields and flagging stale graph IDs. For a single-optional-parameter read tool this is nearly complete; only result-size or pagination expectations for a full listing are unaddressed.

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% and userId is fully documented there, so the baseline is 3. The description never mentions userId or its trial-user usage nuance, adding no parameter 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?

States a specific verb and resource ('List all knowledge graphs the user can access') and enumerates the returned fields (IDs, descriptions, authors, sectors, signal counts). This is clearly distinguishable from siblings like search_graph, get_node, and toggle_graph_preference, which operate on a single graph or its contents.

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 the agent to 'Use FIRST in any session to discover available sources before searching,' establishing sequencing against the search/graph-detail siblings. It also states the downstream purpose: the metadata is needed for graphId parameters in other tools, so the agent knows why and when to call it.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, which signals a mutating, externally-visible operation. The description adds nothing behavioral on top: it never mentions that cancel/pause are state-changing, that creates are non-idempotent (idempotentHint=false), or anything about delivery mechanics. The name's 'manage' hints at a multi-action lifecycle, but the description leaves it undisclosed.

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?

A single tightly written sentence with no filler, front-loaded with 'Use when'. It is efficient, though it spends its one sentence entirely on usage framing rather than distributing attention across purpose and operations.

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?

This is a 6-action lifecycle tool with 10 parameters, a required 'action' discriminator, and no output schema. The description does not explain any action, what each returns, or how schedule_id gates cancel/update/pause/resume. For a tool this complex, the usage-only sentence leaves major operational context missing.

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 90%, so the schema itself documents email, query, brands, graphs, cadence, timezone, report_type, schedule_id, and slack_webhook in detail. The description contributes no additional parameter meaning, and notably never explains the required 'action' enum, which is the one gap the schema leaves. Baseline 3 applies when 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?

The description only frames the tool as usage scenarios ('establishing recurring intelligence tracking', 'setting up automated briefings') and never states what the tool actually does operationally. An agent learns that scheduling is involved but not that it supports create/list/cancel/update/pause/resume. Purpose is inferable from the name and title rather than from the description text.

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 gives clear, concrete when-to-use conditions: recurring tracking, automated briefings, and recurring category/brand shift monitoring. No when-not conditions or alternatives are named, but no sibling tool in the list competes for this scheduling job, so the omission is minor.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true and destructiveHint=false, covering the full safety profile. The description adds non-redundant value by disclosing the return shape ('structured text ready for analysis'), which matters since no output schema exists. It stops short of describing failure modes (paywalls, non-HTML content, fetch errors), which would be useful for a web-fetch tool.

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

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

Three tight sentences with zero filler. The core action is front-loaded ('Extract clean text content from any URL'), followed by the trigger and the return value in descending order of importance.

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 single-purpose fetch tool with a fully-covered schema and complete annotations, the definition covers action, trigger, and output format. The only residual gap is behavior on un-fetchable URLs (auth walls, non-text content), which is a minor omission rather than a blocking one.

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 both parameters (url, userId) are already documented in the schema. The description adds no format detail, validation rules, or clarification about the optional tracking parameter. Baseline 3 is appropriate when the schema does all the work.

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.' The scope ('any URL') and output ('clean text content') are immediately clear. It doesn't explicitly distinguish itself from any sibling, but no sibling in the list performs URL fetching, so the omission is low-cost.

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 gives a concrete when-to-use trigger: 'when a user shares a link (competitor site, news article, client brief, trend report) and wants to cross-reference it against Fodda knowledge graphs.' The examples are helpful context. It lacks any when-NOT-to-use guidance or named alternatives, so it falls short of a 5.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the write nature is already known. The description adds nothing about the operational flow — notably that this is likely asynchronous and results are retrieved via check_deliverable_status, or whether repeat calls duplicate work. Useful output-type detail, but key behavioral context is missing.

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?

A single front-loaded sentence that leads with the trigger condition and then lists concrete examples. No filler, though the examples could have been traded for the missing operational or sibling-routing detail.

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 non-idempotent mutation that kicks off analyst work and has no output schema, the description should explain the follow-up (e.g., use check_deliverable_status to poll results). It covers what the tool produces but omits the lifecycle an agent needs to complete the task 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 all five parameters are self-documenting and the description carries no param burden. Baseline 3 is appropriate. Note a latent inconsistency: the `brief` schema says 'Agents imitate the example in the tool description', yet the description contains no such example.

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?

States a clear verb-plus-resource (commissioning a finished document from an analyst) and enumerates concrete output types (executive briefing, research memo, strategic assessment, article), so the agent knows this produces a written deliverable. It stops short of explicitly naming the sibling it is not — consult_analyst — leaving the distinction to inference from 'finished document'.

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 a positive trigger ('Use when commissioning a finished document'), which is clearer than most siblings. However it names no alternative and gives no when-not condition, so an agent choosing between this, consult_analyst, and check_deliverable_status must infer the boundary itself.

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 non-read-only, non-idempotent, open-world behavior. The description adds genuinely useful process context — a concierge coordinates the introduction and next steps arrive by email (implying an asynchronous, out-of-band response) — but says nothing about auth requirements, response latency, or what the immediate call returns.

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 'Use when' trigger, and the parenthetical scenarios map directly to the usage condition. Slightly dense with stacked qualifiers, but nothing is redundant 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?

For a 5-parameter request tool with no output schema, the description covers the essential flow: who coordinates the intro and how the requester hears back (email). What is missing is the immediate return value of the call and whether the request can be duplicated, but the async nature is adequately conveyed.

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 every parameter (including expert_id's name-or-ID format and message's purpose) is already documented in the schema. The description adds no syntax, format, or routing guidance beyond that, so the 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 states a specific verb+resource (requesting an advisory introduction/consultation) and scopes it to On-Request Human Agents or domain specialists. It distinguishes itself from instant-calendar booking, though it never names the closely related siblings consult_human_agent or consult_analyst, leaving some sibling differentiation implicit.

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 opening 'Use when...' clause gives clear triggering conditions (1-on-1 advisory, strategic projects, no instant booking link), which is more than implied usage. However, it does not explicitly exclude or compare against the sibling consultation tools, so an agent must still infer which of consult_analyst/consult_human_agent/request_expert_intro applies.

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=false, idempotentHint=false, destructiveHint=false and closed-world, so the mutation profile is covered structurally. The description adds useful context about the medium (voice, Google Meet) and duration, but says nothing about side effects, whether re-scheduling replaces a prior booking, or auth requirements.

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 tight sentences, front-loaded with the core action and then the input flexibility. Every clause carries information; zero padding.

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 4-param, no-required, no-output-schema scheduling tool, the description adequately conveys the action and the accepted time inputs. It is slightly thin on post-scheduling expectations (confirmation, link delivery) and parameter interaction, but nothing essential to making the call is missing.

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 all four parameters are already documented in the input schema. The description restates the time-specification options at a high level but adds no format or precedence detail (e.g., what happens if both 'now' and 'datetime' are supplied) 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?

States a specific verb (schedule) and resource (interview), plus distinguishing detail: a 5-10 minute voice interview with the Fodda AI interviewer on Google Meet. No sibling tool competes for this action, but the description is self-sufficient and unambiguous about what it does.

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 explains the three input modes (ISO datetime, human-readable local time, instant now), which implicitly tells the agent how to invoke it, but it gives no when-to-use vs when-not guidance or prerequisites (e.g., whether an account or onboarding is required first).

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, destructiveHint=false, and openWorldHint, so safety is covered. The description adds real behavioral context beyond them: it discloses the return shape (trends + cited evidence + lifecycle stage + next_moves) and cross-graph reachability (100+ graphs). It does not explain the idempotentHint=false nuance or result limits beyond the schema.

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 tight sentences: usage first, then return contract, then sibling routing. No filler, and the most decision-relevant 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?

With no output schema, the description correctly compensates by summarizing the return payload. For a 12-parameter tool it leaves the multi-alias scoping (graph vs graphId vs graphs) and mode=compare semantics to the schema, which is reasonable, but it could say more about graph selection behavior.

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 every parameter (mode, graphs, graphId alias, sector, limit, use_semantic, include_evidence, etc.) is already documented in the schema. The description adds no parameter-level detail such as mode semantics or graph-scoping precedence, so baseline 3 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?

States a specific verb-and-resource (search across 100+ curated knowledge graphs) plus the output contract (trends with cited evidence, lifecycle stage, next_moves). It also names the sibling to use instead for company/brand queries, so an agent can discriminate without opening schemas.

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 when-to-use list (market trends, category dynamics, consumer behavior shifts, competitor intelligence, broad topic investigation) and an explicit routing rule: prefer brand_tracker when the query names a company/brand. The alternatives condition is stated, not implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context: results carry source attribution and parent trend context, and search spans 'all graphs' in parallel. It stops short of pagination or result-volume behavior, so it is strong but not complete.

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, no waste, and the positive scope is front-loaded before the exclusions and alternatives. Every clause routes the agent to a decision.

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 the description conveys what is returned (quotes, analysis, attribution, trend context) and what is not. With annotations covering the safety profile and a 100%-documented schema, nothing an agent needs to call this correctly is missing.

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 every parameter (query, types, sector, graph_id, min_score, limit, userId) is already documented in the schema. The description's mention of 'across all graphs' lightly reinforces the graph_id default, but adds no syntax or format detail beyond the schema. Baseline 3 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?

States a specific scope: 'Narrative and qualitative evidence layer only' returning expert quotes, editorial analysis, and strategic perspectives. It distinguishes itself from siblings search_statistics and get_domain_intelligence by name, so an agent can tell exactly which tool this is without opening a schema.

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 when-not and alternatives: raw statistics go to search_statistics, full trends with bundled evidence to get_domain_intelligence, and company/brand queries to brand_tracker. The conditions that select each alternative are spelled out rather than left to inference.

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 openWorldHint=false, covering the safety profile. The description usefully adds the content boundary (returns only hard numbers, not narrative) and the cross-graph scope (domain, specialist, report graphs). It doesn't address the notable idempotentHint=false or result format, so a 4 rather than 5.

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 tightly packed sentences that are front-loaded with the core purpose before exclusions and sibling routing. Every clause earns its place; no 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?

No output schema exists, but the description fully explains what comes back (figures, percentages, market sizes, growth rates linked to parent trends) and what does not. Combined with rich annotations and a fully documented schema, an agent has everything needed to call it 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 schema already documents all seven parameters including sector scoping, graph_id, min_score thresholds, and limit. The description adds no parameter-level detail (e.g., how sector interacts with graph_id beyond what the schema says), so the baseline 3 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?

States a specific content type ('quantitative statistics and hard numbers layer only') and enumerates what it returns: figures, survey percentages, market sizes, growth rates. It explicitly distinguishes itself from siblings like search_insights and get_domain_intelligence, so an agent can identify it without opening the schema.

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-not guidance ('Does NOT return narrative analysis, trends, or quotes'), names the correct alternatives for those cases (search_insights, get_domain_intelligence), routes company/brand queries to brand_tracker, and gives ordering advice ('Try this before external supplemental data tools'). Full routing decision is encoded.

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 the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely useful context beyond them: that delivery happens through two channels (email and Slack) and targets a specific team, which tells the agent the effect is an outbound notification.

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 front-loaded sentences deliver purpose and trigger conditions with no wasted clauses. The trailing parenthetical '(User feedback logging.)' is mild redundancy with the opening sentence, which keeps it from a perfect score.

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 doesn't need to explain return values, and the annotations carry the safety profile. What an agent needs to call it correctly — purpose, triggers, channels, parameters — is present, leaving only minor gaps like any confirmation or error behavior.

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 four parameters, including the category vocabulary. The description adds no syntax, format, or per-parameter guidance beyond what the schema provides, so the baseline of 3 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 names a specific verb (Forward), a clear resource (user feedback, feature requests, complaints, exit reasons), and the destination (the Fodda team via email and Slack). No sibling tool overlaps this function, so an agent can identify it immediately without opening the schema.

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 gives explicit triggering conditions — call whenever a user shares feedback, with concrete examples (wants to leave, reports a problem, suggests an improvement). It lacks an explicit when-not statement, but no sibling tool competes for this behavior, so the routing guidance is effectively complete.

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 only declare it is a non-read-only, non-idempotent, non-destructive write. The description adds substantial context beyond that: the free tier quota, that a confirmation email is sent, and the strong precondition that user_confirmed must reflect an explicit request. This goes well past the structured fields.

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 core purpose is front-loaded, followed by the critical guardrail, so the ordering is sound and every sentence carries weight. The trailing parenthetical '(User registration and free tier provision.)' is mildly redundant with the opening clause, costing a point.

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

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

For a write tool with no output schema, the description covers purpose, side effect (email), quota, and the confirmation precondition well. It stops short of describing duplicate-email behavior or error handling, which an agent might want, though idempotentHint=false in annotations signals repeat calls are not safe.

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 every parameter including the required user_confirmed flag is already documented in the schema. The description restates the optional profile fields (name, job_title, company) but adds no syntax or format detail beyond what the schema provides, warranting the baseline 3.

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?

States a specific verb and resource ('Create a free Fodda Base account'), names the quota (100 API calls/month across ALL knowledge graphs), and notes the side effect (confirmation email). An agent can distinguish this registration tool from siblings like get_my_account without opening the schema.

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 GUARDRAIL sentence gives explicit when-to-call and when-not-to-call guidance: only after the user explicitly provides an email and asks to create an account, never proactively or with an inferred email. This is exactly the kind of routing/exclusion instruction the dimension rewards.

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 this is a non-idempotent write (readOnlyHint=false, idempotentHint=false). The description adds meaningful context beyond that: this call initializes the session, is where Fodda begins persisting progress, and requires explicit terms acceptance first. It does not describe what a re-call does or the response, but the added behavioral context is substantive.

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 followed by behavioral note and the terms precondition. There is minor redundancy ('begin saving progress' vs 'starts saving the expert's onboarding'), but no wasted scaffolding.

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 9-parameter mutation with no output schema, the description covers purpose, the required terms-acceptance gate, and the state change. It omits what the call returns and where it sits relative to the broader onboarding tool sequence, but nothing essential to correct invocation is missing.

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 9 parameters including the callPrice enum values and the headshotUrl URL-only constraint. The description merely restates a subset of fields (name, role, knowledge area, call rate, bio/headshot), adding no syntax or constraint detail beyond the schema, so the baseline of 3 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 states a specific verb and resource ('Submit basic expert details... to initialize the Human Agent onboarding session') and names the exact fields being submitted. It is clearly a write step in onboarding, distinguishable from read siblings like get_onboarding_status, though it does not explicitly contrast itself with the related begin_expert_onboarding or finalize_byo_mcp_onboarding.

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 gives a clear precondition ('Before calling, show the Terms and Privacy Policy links and get an explicit yes') and identifies this as the step where saving begins. It lacks explicit when-not guidance or routing to the sibling onboarding tools, but the operational context is well established.

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 disclose the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description needn't restate safety. It adds only the workflow sequencing context (advances to theme confirmation) and says nothing about what happens to prior analysis, whether submission can be retried, or validation behavior.

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

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

A single front-loaded sentence with no filler; the action and the next stage are stated immediately. It is efficient, though slightly terse for a workflow-step tool.

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

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

With a fully covered schema and annotations carrying the safety profile, the description only needed to convey workflow placement, which it does. It remains thin on preconditions and the consequence of submission, leaving the agent to infer the surrounding onboarding sequence.

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 four parameters (userId, voiceStudy, expertTopics, termsAccepted) are already documented by the schema. The description adds no parameter-level detail beyond what the structured field already provides, making the baseline of 3 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?

States a specific verb (submit) and resource (analyzed voice study and expertise map) and ties it to the next workflow stage (theme confirmation). It distinguishes itself reasonably from siblings like submit_basic_info by naming the specific artifacts, though it doesn't explicitly differentiate against the other submit_* onboarding 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?

"To proceed to theme confirmation" implies this is a sequential onboarding step, which gives some usage context. However there is no explicit when-to-use-vs-alternative guidance or stated prerequisites (e.g., that basic info must be submitted first, or that confirm_themes follows).

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=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the agent already knows this reaches outside the system and mutates state. The description adds that it performs discovery of available tools and derives coverage, but does not disclose side effects such as whether the endpoint is persisted, whether repeated calls create duplicate sources, or any auth/rate-limit constraints beyond what the schema's enum notes say.

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 compact sentences with no filler, and the core action is front-loaded. It could be slightly tighter, but nothing is wasted.

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 non-idempotent external-network tool with no output schema, the description should say what the probe yields or persists and what success looks like. It gestures at 'derives topic coverage' but leaves the return/state outcome unspecified, so the definition is adequate but incomplete.

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% and each parameter (mcpUrl, userId, mcpAuthType) is documented in the schema, including the Phase 1 'none'-only restriction. The description adds no syntax, format, or validation detail beyond the structured fields, so the baseline 3 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?

States a specific verb pair (connect and probe) and a specific resource (BYO-MCP endpoint), plus the downstream purpose (topic coverage for profile modeling). It is clear what the tool does, though it never names the sibling tools in the onboarding flow (e.g. begin_expert_onboarding, finalize_byo_mcp_onboarding) that an agent must sequence it against.

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 implies this is a step in expert onboarding but gives no explicit when-to-use, no prerequisites (e.g. that a user/expert context must exist first), and no alternatives to compare against. An agent must infer its place in the onboarding sequence from the sibling names alone.

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