concord-mcp

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

The description adds substantial behavioral detail beyond the annotations: ranking by votes, include_text behavior, limit defaults and caps, returning the true total, and target formatting. This gives the agent a strong understanding of what to expect from the 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?

The description is front-loaded with the core purpose, then usage guidance, then detailed behavior. It is moderately long but every sentence contributes useful information without filler, making it appropriately concise for the depth provided.

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

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

Given the tool's moderate complexity, the presence of an output schema, and clear annotations, the description covers all necessary aspects: when to use, how it behaves, parameter effects, and return structure. It is fully adequate for an agent to invoke 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 coverage is 100% for all three parameters, so the baseline is 3. The description repeats some schema details (e.g., include_text, limit) but does not introduce new parameter semantics beyond what the schema already documents.

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

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

The description clearly states the tool's function: 'List the passages traditionally linked to a verse or passage.' It distinguishes itself from sibling lookup_verse by explicitly mentioning the use case 'what other passages relate to this one?' and naming the sibling tool, making it obvious when to choose this 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 provides explicit usage context: 'Use after lookup_verse when the question is...' and gives concrete examples. However, it does not explicitly specify when not to use the tool or mention alternatives other than lookup_verse, though the implied use case 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 the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it explains the two-step list/detail pattern, the nature of the data ('commonly proposed reconstructions, not certainties'), and specific fields ('honesty status', 'coordinates where confident'). This enriches understanding without contradicting annotations.

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

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

The description is two sentences long, front-loaded with the purpose, and every sentence earns its place. It efficiently covers the two modes of use and the important caveat about reconstructions, with no wasted words.

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

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

Given the tool's simplicity (one optional parameter, no required args) and the presence of an output schema, the description is highly complete. It explains the list and detail workflows, what to expect in the output (stops, honesty status, coordinates, verses), and the epistemic status (commonly proposed reconstructions). There are no significant gaps for an agent to invoke and interpret results 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?

The input schema already provides full coverage (100%) for the single parameter journey_id, with a description explaining its meaning and default behavior. The tool description reiterates this usage ('Call with no arguments... then call again with a journey_id') but adds no new semantic information beyond examples. Since the schema does the heavy lifting, a score of 3 is appropriate.

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

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

The description clearly states the tool's purpose with specific verbs: 'Browse the curated biblical journeys, or get one journey's ordered stops.' It distinguishes from sibling tools by focusing on curated journeys rather than individual verses or words, and provides examples of journey ids. This is a clear, specific, and distinct purpose.

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

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

The description provides explicit usage guidance: 'Call with no arguments to list the journeys... then call again with a journey_id for the detail.' This tells the agent when to call with and without arguments. It does not explicitly mention alternatives or when not to use the tool, but the guidance is clear enough for correct invocation.

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

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

Annotations already state readOnlyHint=true and idempotentHint=true, so the description isn't burdened with safety disclosure. It adds valuable behavioral context: returns each verse on its own line, tags verses with 'Book Chapter:Verse (TRANSLATION)', supports side-by-side translation comparison, and mentions the default translation (KJV). No contradiction with annotations.

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

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

The description is four sentences, front-loaded with the core purpose, followed by usage, output format, and alternative guidance. Every sentence earns its place; no fluff or repetition.

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

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

The tool has an output schema for return values, so the description needn't explain them. It covers accepted input forms, translation behavior, default, output formatting, and when to use alternatives. For a 2-parameter lookup tool with rich annotations and output schema, this is fully 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%: both 'reference' and 'translations' have detailed schema descriptions. The description adds examples ('John 3:16', 'Genesis 1:1-5', ['KJV','WEB']) and reinforces the default, but doesn't introduce meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Fetch the exact text of a Bible verse, verse range, verse list, or whole chapter.' It clearly distinguishes from siblings by stating it is for when you already have a reference, unlike search_keyword or search_by_meaning.

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

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

Explicit usage guidance is provided: 'Use this whenever you already have a reference' and 'If you don't have a reference, use search_keyword ... or search_by_meaning.' This directly tells the agent when to use this tool versus named alternatives.

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

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

The description goes well beyond the read-only and idempotent annotations by disclosing the honesty policy: 'identified' and 'disputed' come with coordinates, while 'unknown', 'symbolic', and 'multiple' state plainly that no single pin exists — never a guessed location. It also states that passages with no places explicitly say so, adding behavioral transparency not present in the structured annotations.

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

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

The description is moderately sized but front-loads the core purpose in the first sentence. Each subsequent sentence adds necessary detail about confidence statuses and the no-places case. It could be tightened slightly, but it is not bloated and every clause contributes meaningful 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 a single parameter, an output schema, and strong safety annotations, the description still covers the output line format (name, type, honesty status), the handling of disputed vs. unknown locations, and the edge case of no places. This is comprehensive for a tool of this complexity.

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

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

The schema already provides full coverage of the single parameter 'reference' with a clear description and examples. The tool description echoes the same examples and adds no new semantic detail beyond what the schema specifies. Thus the baseline of 3 is appropriate.

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

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

The description opens with the specific action 'List the places a passage names' and clarifies the confidence-based coordinate handling. It distinguishes itself from sibling tools by focusing on place identification for a passage, with examples like 'Acts 17' and 'Genesis 4:16', making the tool's purpose unmistakable.

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 states when to use the tool: 'after reading a passage when the question is where did this happen?' This provides clear context and a usage scenario. However, it does not name alternatives or exclusions, so it falls short of the 'when-not-to-use' guidance that would merit 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=true, so no safety concerns. The description adds valuable behavioral details: each call returns a different verse, the response is tagged with 'Book Chapter:Verse (TRANSLATION)', and contradictory filters produce a 'no verse matches' message. This goes beyond what annotations provide, though it stops short of exhaustive behavior.

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

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

The description is compact and front-loaded with the core purpose, followed by filtering options and return behavior. Every sentence adds value, with no fluff or repetition of schema details.

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

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

Given an output schema exists and the tool has only three optional parameters, the description fully covers use cases, filtering, randomness, and error handling. It is complete for the complexity of the tool.

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

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

Schema coverage is 100% so the baseline is 3. The description enhances the schema by giving concrete examples ('John', 'PSA'), clarifying the default translation (KJV), and explaining the contradiction behavior when book and testament conflict. This adds meaningful context not present in the property descriptions alone.

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

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

The description begins with 'Fetch one random verse' — a clear verb+resource combination. It lists concrete use cases (verse of the day, writing prompt, sampling a book's voice) and distinguishes itself from sibling tools like lookup_verse and search_by_meaning by emphasizing randomness.

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 directly states when to use the tool (verse of the day, writing prompt, sampling a book's voice) and explains the optional filtering options. It does not explicitly name alternative tools or give 'when not to use' guidance, which would push it to a 5, but the context is clear.

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

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

Annotations already declare readOnly and idempotent hints, so the description adds valuable non-obvious behavior: ranking by closeness of meaning, result limits and defaults, tagging with reference/translation, similarity scores, and the min_score threshold. No contradiction with annotations.

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

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

The description is front-loaded with purpose and usage, then covers parameters and alternatives. It is somewhat lengthy but each sentence adds information. Minor redundancy exists (e.g., mentioning ranking and then similarity score), but overall it is well-organized and not 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?

Given the presence of an output schema, the description doesn't need to detail return shapes. It fully covers purpose, when to use, parameter behavior, output characteristics, and sibling alternatives. No obvious gaps remain for an agent to correctly select and invoke the tool.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds context beyond the schema by integrating parameters into the tool's narrative (e.g., 'can be returned in any loaded translation', 'set min_score to drop weak matches') and providing examples for query. It slightly exceeds the baseline due to this contextual enrichment.

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: 'Find Bible verses by meaning rather than exact wording.' It clearly distinguishes itself from siblings by explicitly naming lookup_verse, search_keyword, and topic_verses as alternatives for different use cases.

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 'Use this when' guidance with concrete examples ('verses about anxiety', 'the good shepherd') and clear when-not-to-use instructions: 'If you already know the reference, use lookup_verse instead; if you need an exact word or phrase match, use search_keyword.' Also covers topic_verses for curated subjects.

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 (readOnly, idempotent, non-destructive), the description discloses exact-match behavior, the default KJV translation, ability to pass multiple translations side by side, result limit and true total, and that [excerpt] lines are partial. It also notes that lines are tagged for lookup_verse, which helps the agent know how to handle partial results.

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 composed of five sentences, each adding substantive information without redundancy (except a slight repeat of lookup_verse in the excerpt clause). It is compact and front-loaded, with the core purpose in the first sentence, followed by usage and details.

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

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

For a search tool with 3 parameters and no output schema provided, the description explains return behavior (limit, total, excerpt tags, lookup guidance), which is essential. It also covers alternatives and translation behavior, leaving no major questions about how to use the tool or interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful examples and clarifications, such as quoting multi-word phrases, the server's configured KJV, and the 'side by side' behavior for translations. This surpasses the schema's basic descriptions but does not need to compensate for missing schema info.

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

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

The description states it 'Find verses containing an exact word or phrase' with a specific verb and resource, and explicitly distinguishes it from lookup_verse (by reference) and search_by_meaning (by ideas). This makes the tool's purpose unmistakable.

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 'Use this when the wording matters' and provides concrete examples ('propitiation', 'still waters'). It also gives clear alternatives: 'If you have a reference, use lookup_verse; for ideas rather than wording, use search_by_meaning.' This is exemplary 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?

Even though annotations already indicate read-only and idempotent behavior, the description adds valuable behavioral details: include_verses lists verses 'up to limit, default 10, max 25, with the true total', and 'each verse tagged so you can lookup_verse it'. It also notes accepted id formats ('g26' and 'G0026'). These go beyond the annotations and schema, providing operational context.

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

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

The description is three sentences, each with a distinct purpose: main lookup capability, usage conditions, and parameter behavior. It front-loads the primary function and remains tightly packed without redundancy. Every clause adds information, making it appropriately sized for the tool's complexity.

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

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

Given the output schema exists and annotations cover safety, the description completes the picture by specifying the return content (lemma, transliteration, gloss, definition), the optional verse listing behavior, and the relationship to lookup_verse. There are no obvious gaps for an agent to invoke the tool correctly.

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

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

The schema already describes all three parameters with 100% coverage, giving a baseline of 3. The description adds further meaning by providing concrete examples for strongs_id, explaining the verse-count behavior of include_verses (limit cap, true total), and clarifying that verses are tagged for lookup_verse. This extra semantic value lifts the score above baseline, though not a full 5 since the schema already covers the basics.

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

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

The description clearly states the tool's function: 'Look up a Strong's lexicon entry — lemma, transliteration, gloss, and full definition — by its id'. The verb 'look up' and the specific resource (Strong's lexicon entry) make the purpose unambiguous, and the mention of id formats like 'G26' and 'H7225' differentiates it from sibling tools like lookup_verse and word_study.

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

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

The description explicitly tells when to use the tool: 'Use after word_study surfaces an id, or whenever a Strong's number appears.' It also provides an exclusion: 'For the words of a specific verse, use word_study with the reference instead.' This directly names an alternative and gives clear decision 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond these hints: it mentions that 'See X' redirects are followed and labeled, that the tool returns the true total along with up to limit verses, and that ambiguous names produce a candidate list. This goes beyond the safety profile provided by annotations.

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

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

The description is concise and front-loaded. Four sentences each serve a distinct purpose: stating the core function with examples, giving usage guidance with an alternative, explaining the ambiguity handling, and describing output limits and tagging format. No wasted words.

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

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

Combined with rich annotations (read-only, idempotent) and an existing output schema, the description is highly complete. It covers when to use, when not to, behavior for ambiguous names, redirect handling, limit semantics, and output formatting, leaving no critical gaps for an agent to invoke 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%, with each parameter (topic, limit, include_text) already well documented. The tool description reinforces the default limit and candidate-id behavior but does not add substantial new semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool looks up a subject in Nave's Topical Bible and returns its verses, with concrete examples ('faith', 'care', 'prayer'). It explicitly distinguishes itself from search_by_meaning by noting it returns the editor's chosen verses rather than a similarity search, which differentiates it from siblings.

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

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

Explicitly specifies when to use this tool ('what does the Bible say about X?' for classic study subjects) and when not to, directing users to search_by_meaning for non-index phrasings like 'feeling overwhelmed at work'. It also explains the flow for ambiguous topics, telling the agent to call again with a listed id.

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/destructive=false, so the bar is lower. The description adds valuable context: automatic language selection, the structure of each word line, verse block labeling, and the output cap. This goes beyond simple safety flags and helps set expectations, though it could mention error handling or edge cases.

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?

Concise and well-organized, starting with the core purpose, then usage guidance, then output details and constraints. Each sentence carries useful information, though the list of fields per word line is a bit dense. Overall it is appropriately sized for a tool with this complexity.

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 one parameter and an output schema, the description is complete. It explains the return structure (word lines with position, lemma, etc.), the pragmatic use case, and the output cap. No significant gaps remain.

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

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

The input schema already covers 100% of the parameter (reference) with description and examples. The tool description reiterates the 'short passage' and 'capped at 10 verses' constraints but doesn't add new parameter-specific meaning beyond what's in the schema. It's at the baseline for full schema coverage.

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

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

The description opens with a specific verb-object pair: 'Show the original-language words behind a verse or short passage,' and clarifies the Greek/Hebrew split. It distinguishes itself from siblings by emphasizing wording and nuance, and provides a concrete example ('John 21:15-17') that makes it unmistakable.

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

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

Explicitly states when to use the tool: 'Use when the question is about wording, nuance, or "what does this word really mean?"' and gives a clear example. It also differentiates from the strongs_entry tool by telling users to follow Strong's IDs with strongs_entry, and advises keeping references short due to the 10-verse cap.

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