Fikra MCP

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

The description adds genuinely useful non-schema context: a fixed price of $0.75 per call, which annotations do not convey. However, it says nothing about how the 'perspective' choice alters results, what happens on very long documents, or why readOnlyHint=false and idempotentHint=false are set for what reads as an analysis operation.

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 deliverable and provenance. The third sentence largely restates the purpose already implied by the first, so it is mildly redundant rather than 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 does state the return shape (risky clauses plus their section) and the cost, which covers the essentials for a 2-parameter tool. It still leaves undefined what counts as 'risky', the ordering/format of results, and document size limits.

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 are already documented in the schema. The description adds no meaning beyond that — notably it never mentions 'perspective' (which party you represent) or how it changes the risk output.

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?

Specific verb+resource: 'List risky or unusual clauses' plus the output shape ('with the section they came from'). This distinguishes it implicitly from siblings like fikra_extract_contract_obligations and fikra_summarise_contract, but no sibling is named 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 closing sentence ('Reading a long contract and finding the clauses that need attention') supplies an implied use case, but there is no explicit when-to-use rule, no exclusion, and no routing to alternatives such as fikra_summarise_contract or fikra_compare_contracts.

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

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

The description adds one genuinely behavioural fact not in the annotations: a fixed price of $0.50 per call, which matters because idempotentHint=false means repeated calls incur repeated cost. Beyond that it is silent on what happens to the submitted document, whether results are stored, or what the response looks like — and with readOnlyHint=false the agent has no annotation-based reassurance about side effects.

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 fragments, no filler, with the covered terms front-loaded. It is slightly telegraphic — the price sentence sits between the capability and the use case — 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?

For a single-input analysis tool with no output schema and no annotations describing side effects, the description is adequate but thin: it names the topics it will cover yet says nothing about the shape of the returned explanation or how long/detailed it will be, so an agent cannot predict 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?

There is a single parameter ('document') with 100% schema description coverage, so the 3 baseline applies. The description adds nothing about expected format, length limits, or whether plain text versus pasted markdown is acceptable for the document.

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 gives a specific verb ('Explain') and enumerates the contract domains covered: salary, notice, non-compete, confidentiality and termination. That differentiates it reasonably well from sibling extractors (fikra_extract_contract_obligations, fikra_extract_contract_dates) and summarisers, though it never names those siblings 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 closing phrase 'Understanding an offer or employment agreement before signing' implies the usage context (pre-signature review of an employment offer), which is more than nothing. However, no alternatives are named and no exclusions are stated, so an agent must infer why it would pick this over fikra_summarise_contract or fikra_analyse_contract_risks.

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 $0.05 fixed price per call is genuinely useful context that the annotations do not convey, and it explains the readOnlyHint=false billing side effect. However, nothing is said about input size limits, what the failure-pattern output looks like, or why the call 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 short sentences, front-loaded with the core action and cost, which is good. But the third sentence ('Spotting the real error in a noisy log') largely restates the first and adds no new 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?

No output schema exists, so the description must carry the burden of explaining the return value, and it does not. Combined with undocumented parameters and no usage routing against similar diagnostic tools, the definition is under-specified for a paid analysis 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 0% for two parameters. The description implies the 'logs' input via 'log excerpt' but never explains its format, size expectations, or what the optional 'context' parameter is for — a real gap the description should have filled.

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: find the failure pattern in a log excerpt. The scope (log excerpt, noisy logs) distinguishes it from siblings like fikra_debug_sql or fikra_diagnose_api_error, though it never names those alternatives 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?

No when-to-use or when-not-to-use guidance. With close siblings such as fikra_debug_sql, fikra_diagnose_api_error, and fikra_explain_json in the catalog, the agent is left to infer which tool suits a given troubleshooting input.

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 non-read-only, non-idempotent, non-destructive, closed-world, and the description adds genuinely useful context the annotations cannot: a fixed $0.05 per-call price, which is a real side effect and justifies readOnlyHint=false. However, it says nothing about input size limits, what happens with malformed specs, or what the summary output looks like, so the behavioral picture is only partially filled in.

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, front-loaded sentences with no filler; the capability, the price, and the use case appear in that order. The final sentence is a fragment rather than a clause, which is slightly informal but costs no clarity.

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 one-parameter analysis tool with no output schema, the description does a reasonable job by enumerating the output sections (endpoints, auth, schemas, errors) and disclosing pricing. Missing only edge-case handling guidance such as spec size limits or behavior on invalid YAML/JSON.

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?

There is a single required parameter with 100% schema description coverage ("OpenAPI JSON or YAML text."), so the schema already carries the semantics and the baseline is 3. The description adds no constraint such as size limits, whether a URL is accepted versus raw text, or supported OpenAPI versions.

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 (Summarise) and a specific resource set (endpoints, auth, schemas, errors from an OpenAPI document), so the agent can distinguish it from adjacent API tools like fikra_diagnose_api_error or fikra_generate_api_tests. It stops short of naming the nearest sibling explicitly, so it is clear but not fully differentiated.

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?

"Understanding a large API before integrating" implies a usage context, but there is no explicit when-to-use rule, no when-not-to-use rule, and no alternative named (e.g. explain_json or diagnose_api_error for smaller or error-specific cases). The agent must infer routing from the resource description alone.

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 price disclosure ("Fixed price $0.30 per call") is genuine added value the annotations do not carry, and it usefully explains why readOnlyHint is false despite this being an analysis operation. The description still does not say what a "gap" is, how documents are processed, or whether results are cached/returned inline, but the cost-transparency contribution 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 short sentences, front-loaded with the action and the price, with no filler. The closing sentence is largely a restatement of the first and could be dropped in favor of the missing document-format guidance.

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 clarify the return shape — is it one summary block per document, and what constitutes a "gap"? It also leaves the document input format undefined. The cost line is a helpful start, but for a paid, non-read-only analysis call this is only minimally sufficient.

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?

There is one required parameter, `documents`, at 0% schema description coverage, and the description says nothing about it — not the accepted format (raw text, file paths, base64, URLs), not how many are allowed, not whether suppliers map one-to-one to array entries. With only one parameter there was ample room to compensate, and it did not.

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 (summarise) plus a resource (each supplier quote) and a second action (flag gaps), which is clear enough to distinguish it from fikra_generate_procurement_report or fikra_extract_purchase_order. It does not, however, distinguish itself from the very close sibling fikra_compare_quotations, which an agent would plausibly reach for instead.

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?

"A quick read of what each supplier is actually offering" implies a lightweight, per-quote orientation pass, but there is no explicit when-to-use, no when-not-to-use, and no mention of the sibling comparison/analysis tools. Usage must be inferred from the name and the hint of "quick."

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

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

The description discloses a concrete operational trait not present in annotations: a fixed $0.20 charge per call, which matters for a non-readOnly, non-idempotent tool an agent may call repeatedly. Annotations already cover the safety profile (destructiveHint=false, openWorldHint=false), so the remaining gaps — no description of the returned structure or of what happens on repeat calls — are tolerable at this level.

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 with no filler, and the core action is front-loaded. The final fragment, "Getting transactions ready for bookkeeping," is the weakest line — it restates intent vaguely rather than adding routing information — but it is brief enough not to hurt.

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 two-parameter, no-output-schema tool, the description should say roughly what comes back (e.g. the original lines annotated with a category, and what happens to uncategorisable lines). It covers cost and rough intent but leaves the return shape and the optional categories parameter's behaviour undocumented, so an agent must infer 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?

Schema description coverage is 100% and both parameters (document, categories) are documented in the schema itself, so the baseline of 3 applies. The description adds nothing about parameter format, e.g. whether categories is comma-separated or free text, or how the model behaves when categories is omitted.

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 first sentence gives a specific verb and resource: assign a category to each expense line. That is enough to separate it from extraction siblings like fikra_extract_invoice or fikra_process_receipt, but the description never names those siblings or states the boundary explicitly, so differentiation is inferred rather than stated.

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?

"Getting transactions ready for bookkeeping" implies a workflow stage (post-extraction, pre-reporting), which is useful implied context. However there is no explicit statement of when to choose this versus fikra_process_receipt, fikra_generate_expense_report, or fikra_reconcile_invoice_receipt, and no prerequisites are given.

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

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

With no annotations, the description carries the full burden, and it does disclose the notable behavioral trait of cost and auth ('Paid per call (x402 USDC or API key)'). It still omits output format, latency/streaming behavior, failure modes on insufficient payment, and whether generation is deterministic.

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 short sentences with the core action front-loaded and the payment condition appended; no filler. Slightly terse given how much is left unspecified, 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?

There is no output schema, no annotations, and 0% schema coverage, so the description is the only source of truth. It fails to explain the return shape, the messages array format, or what a caller should do after listing models, leaving an agent under-equipped for this paid generative 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 0% with 3 parameters (model, messages, max_tokens), so the description must compensate and largely does not. 'with a Fikra model' only obliquely hints at the model parameter, and the shape of messages and the meaning of max_tokens are left entirely undocumented.

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: 'Generate a response with a Fikra model.' It is clearly distinguishable in kind from the sibling fikra_list_models, though the description never names that sibling to reinforce the split.

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 when-to-use or when-not-to-use guidance and no mention of the sibling fikra_list_models as the prerequisite for discovering a model name. Usage is only weakly implied by 'chat' semantics.

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

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

With no annotations, the description carries the full disclosure burden and delivers little: it does not say whether the call is read-only, idempotent, or safe to poll, nor what statuses can come back (pending/completed/failed) or whether a missing reference errors. The one useful disclosure is 'Free', which tells the agent this call consumes no credits.

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 very short sentences, front-loaded with the action and the key, and no filler. Every word earns its place, including the pricing note.

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 an operation whose whole purpose is status polling, the definition lacks the return-value framing (possible statuses, terminal vs non-terminal), the source of the reference, and any no-annotations behavioral context. No output schema exists to offload that burden, so the description leaves the agent guessing.

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

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

Schema coverage is 0%, so the description must carry the semantics; it does establish that 'reference' is the top-up reference rather than an invoice or customer reference. It adds no format, source, or example beyond that, so it only partially compensates for the schema gap.

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 gives a specific verb and resource ('Check a top-up') and names the lookup key ('by its reference'), which distinguishes it from siblings like create_topup_checkout and get_balance. It stops short of explicitly contrasting itself with those siblings, but the resource is unambiguous.

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

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

There is no explicit when-to-use guidance, no mention of where the reference comes from (presumably fikra_create_topup_checkout), and no indication of whether this is meant for polling after checkout. Implied usage only, with no alternatives or exclusions named.

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 contributes the fixed price of $0.30 per call, which annotations cannot convey, and that is genuinely useful for a paid tool. However it does not explain why readOnlyHint=false and idempotentHint=false (presumably credit consumption per call), nor whether cost scales with the number of CVs supplied. Safety profile itself is already covered by annotations.

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

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

The first sentence is front-loaded and the price sentence earns its place. The closing tagline "Shortlisting without reading every CV twice" is marketing flourish that tells an agent nothing operational, consuming a third of a very short description.

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 hint-level annotations, the description should explain the shape of the result (per-CV scores? ranked list? gap bullets?) and the input format. It instead stops at a one-line intent plus price, leaving an agent unable to predict or rely on the response structure.

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

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

Schema description coverage is 0%, so the description carries the full burden for both required parameters. "CVs against a role" loosely maps cvs and job_description, but nothing says whether each CV is raw text or a URL, what the maximum array length is, or how content length affects cost — the details an agent needs to construct a valid call.

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?

"Compare CVs against a role and summarise fit and gaps" gives a specific verb (compare) plus both resources (CVs, role) and the output intent (fit and gaps). It implicitly distinguishes itself from fikra_screen_cv by operating on multiple CVs, but never names that sibling to make the boundary explicit.

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 tagline "Shortlisting without reading every CV twice" gestures at the use case but gives no when/when-not guidance. With close siblings like fikra_screen_cv, fikra_tailor_cv and fikra_extract_job_requirements, an agent gets no routing signal for batch screening vs single-CV screening vs requirement extraction.

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 destructiveness (false) and world scope (false), so the description's main added value is the fixed $0.50 per-call price and the 'material differences' output focus. It does not contradict the non-read-only annotation; the paid-per-call model is consistent with readOnlyHint=false. It stops short of describing output format or latency.

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 core action. The pricing sentence interrupts the flow slightly but is short and relevant.

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-parameter comparison tool with no output schema, the definition covers purpose, price, and a use case. It is still missing the key operational detail — the required format of each document string — and any hint about the shape of the returned differences.

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

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

Schema coverage is 0% and the single `documents` parameter is an untyped array of strings. The description implies the array should contain exactly two contracts, which is useful, but it does not say whether these are IDs, file paths, URLs, or raw text — the caller still has to guess.

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 ('Compare two contracts') plus the output intent ('show material differences'). It is distinguishable from fikra_summarise_contract and fikra_analyse_contract_risks, though it never explicitly names those 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?

'Checking a redline actually changed what was agreed' supplies a concrete use case, which is better than nothing. However, there is no explicit when-not guidance and no named alternative (e.g., summarise_contract for a single document).

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

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

The description adds a genuinely useful behavioral fact not present in annotations: a fixed price of $0.20 per call. Annotations already cover the side-effect profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the remaining gap is only the return shape, which the phrase 'list differences' loosely implies.

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 fragments with the core action front-loaded and no filler. The final fragment is slightly elliptical (lacks an explicit subject) but still reads cleanly.

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 one-parameter comparison tool with no output schema and annotations that cover safety, the description covers action, inputs, cost and intent. The only omission is what the difference output looks like, which is minor given the tool's simplicity.

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 is documented as 'Two or more invoice texts.' The description's 'two or more invoices' corroborates but does not extend the schema — it doesn't clarify whether full raw text or extracted fields are expected, nor any length limits. 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 ('Compare two or more invoices and list differences') and scopes the comparison to amounts, tax and line items. Among the many fikra_compare_* siblings, the resource is unambiguous, so an agent can route to it without opening sibling 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?

The trailing phrase 'Spotting a changed amount, tax or line item across versions' implies the use case (version-to-version invoice diffing) but never states when to prefer this over fikra_compare_purchase_orders, fikra_reconcile_invoice_receipt, or fikra_extract_invoice_fields. Usage is inferable rather than explicit.

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?

Adds a genuinely useful behavioral fact not present in annotations: a fixed $0.01 charge per call. That is important since readOnlyHint=false makes it non-obvious the tool costs money. It doesn't disclose return shape or whether repeated calls re-charge, but annotations already carry idempotency and destructiveness hints.

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 short sentences, front-loaded with the action and dimensions, followed by the pricing fact. The second sentence is a bit marketing-flavored but still conveys use context, 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?

For a two-param tool with no output schema, the description should hint at what the comparison returns (per-model breakdown? ranking?), and it does not. The pricing and cardinality notes are helpful, but an agent still cannot anticipate the response.

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

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

Schema description coverage is 0%, so the description must compensate. "Two or more models" usefully conveys the array cardinality constraint, and "fit for a task" maps to the optional task param. However, it never says whether model entries are names, IDs, or provider-prefixed strings, leaving a real ambiguity.

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 (compare) and resource (models) plus the comparison axes: price, context window, and task fit. An agent can distinguish it from fikra_list_models or fikra_get_tool_prices, though the description doesn't name those siblings 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?

"Choosing a model without reading five pricing pages" implies the use case (model selection), which is helpful framing. But there is no explicit guidance on when to use this versus fikra_estimate_inference_cost or fikra_list_models, and no preconditions such as valid model identifiers.

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?

Adds genuinely useful context beyond annotations by disclosing a fixed $0.30 per-call charge, which explains the non-read-only annotation (metered operation). However, it omits other behavioral facts an agent needs: whether the charge applies on error, whether the call is synchronous or long-running, and why readOnlyHint is false for what is logically an analysis operation.

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, purpose front-loaded, with cost stated up front rather than buried. The closing sentence is close to redundant with the first but does carry a usage framing, so the waste is minimal.

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 no parameter documentation, the description should explain the shape of the comparison result (e.g. a diff of mismatched line items) and the document input format. It does neither, leaving an agent unable to prepare a correct call or anticipate the response for a paid operation.

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

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

Schema description coverage is 0% and the single 'documents' array parameter is completely undocumented. The description implies the array should carry two items (two PO versions, or one PO plus one quote), which is real added meaning, but it says nothing about item format (file path, URL, ID, or raw text), count limits, or ordering semantics.

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 ('Compare PO versions') and enumerates the two comparison modes: PO-to-PO and PO-to-quote. Sibling tools like fikra_compare_quotations and fikra_compare_invoices are separable by resource name, though the description never explicitly contrasts 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?

'Confirming an order matches what was agreed' gestures at the intended use case, but there is no explicit when-to-use / when-not guidance and no named alternative (e.g. fikra_compare_quotations for quote-vs-quote work). An agent must infer the decision boundary from the resource name alone.

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=false, destructiveHint=false, openWorldHint=false, idempotentHint=false). The description adds behavior annotations don't carry: a fixed $0.50 charge per call, which explains the non-idempotent billing side effect and is genuinely useful for agent cost decisions. It stops short of describing how results are ordered or returned.

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 price are front-loaded in two compact sentences. The final fragment ('Choosing between quotes without missing the cheapest…') reads like an unfinished sentence and adds little, but overall there is almost no 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?

With no output schema and no annotations explaining return values, the description should say more about what 'name the best offer' produces (single winner? ranked table? rationale?). The critical gap is the opaque 'documents' input format, leaving the definition only marginally complete for a billed 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?

There is one parameter, 'documents', an array of strings with 0% schema description coverage. The description never explains whether those strings are file paths, document IDs, raw quote text, or URLs — the single most important thing an agent needs to supply a valid call. No value is added beyond the bare 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: 'Compare supplier quotes on price, terms and completeness, and name the best offer.' This clearly separates it from data-extraction siblings like fikra_extract_purchase_order or single-document analysis like fikra_analyse_supplier_quotes, and it even states the output (a named best offer).

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 trailing clause 'Choosing between quotes without missing the cheapest or the best terms' implies the use case but gives no explicit when-to-use rules, prerequisites, or named alternatives (e.g. fikra_analyse_supplier_quotes vs this comparison tool). Usage is inferable rather than 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?

With no annotations, the description carries the full behavioral burden. It does disclose real behavior beyond the schema — fixed FX at KES 133 = $1, wallet credited in USD, 'Free; the charge happens at payment' — which is genuinely useful. However, for a payment-initiating mutation it omits whether repeated calls create duplicate top-ups (idempotency), what 'confirm' does, whether a phone prompt is triggered, and what is returned (a URL, a pending state).

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 dense sentences, front-loaded with the action and payment channels, followed by the pricing/FX constraint. No filler, though the pricing sentence could be tightened and would read better after a line about the amount parameter.

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?

Six parameters, 50% schema coverage, no annotations and no output schema, yet the description covers only channels and FX. For a financial action that spends real money, it should say what is returned, whether the call is repeatable, and what amount_usd/confirm control.

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 50%, and the description adds nothing about the four undocumented parameters: 'phone', 'confirm', and especially 'amount_usd' are never mentioned, so an agent cannot tell what amount_usd represents, whether it is required (the schema lists no required fields), or how currency interacts with it. The FX sentence adds meaning only for 'currency', which the schema already annotates as 'the charge is always KES'.

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 ('Create a top-up for the wallet') and names the two accepted payment channels (card, mobile money with M-Pesa/Airtel examples). It is clearly distinguishable from fikra_check_topup_status and other billing siblings, 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?

Usage is implied by the verb and the payment-channel enumeration, but the description gives no explicit when-to-use, no prerequisites (auth, phone ownership), and no pointer to fikra_check_topup_status for follow-up. An agent must infer the workflow entirely 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?

The description adds genuinely useful metadata beyond annotations: a fixed $0.05 per-call price, which matters for a paid operation. However, it does not disclose what the response looks like (no output schema exists) or how the error/schema/dialect inputs change behavior. Annotations (readOnlyHint=false, destructiveHint=false) do not contradict the description, since the tool only analyzes and suggests a fix, but the description does not explain the non-read-only flag either.

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 with the core action front-loaded, but the final sentence ('Debugging a slow or wrong query') restates the first with a drift in scope and earns little. The price sentence, by contrast, is well placed.

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 four undescribed parameters, no output schema, and sparse annotations, the description is too thin. It never explains what the fix output contains, whether the DB schema input is DDL or a description, or which SQL dialects are supported.

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

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

Schema description coverage is 0% across four parameters, so the description carries the full burden and largely fails: query and error are only obliquely implied, and schema and dialect are never mentioned. An agent must guess the format and purpose of each input from the bare names.

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: explain why a query fails or returns wrong rows and produce a fix. This is clear enough to act on, but there is no explicit differentiation from nearby siblings such as fikra_diagnose_api_error or fikra_analyse_logs, which an agent could plausibly confuse with SQL debugging.

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 trailing phrase 'Debugging a slow or wrong query' implies a usage context, but no when-not conditions or alternatives are named. Performance ('slow') is mentioned only in the final fragment and is not reconciled with the main 'fails or wrong rows' framing.

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 (destructiveHint=false, openWorldHint=false), and the description adds genuinely useful behavior the annotations do not convey: a fixed price of $0.10 per call. That cost disclosure matters for an agent deciding whether to invoke it. It still doesn't explain why readOnlyHint is false for what reads like a pure analysis call, nor what the response contains.

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 pricing are front-loaded in two tight sentences. The closing fragment 'Debugging an integration failure quickly.' is the weakest element, partly duplicating the first sentence and reading as a tagline rather than 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 four parameters, the description should say something about the shape of the answer (a named cause plus a proposed fix?) and how inputs are read. It gives a rough outcome concept but leaves an agent guessing about return format and input encoding, so it is only minimally adequate.

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

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

Schema description coverage is only 50%: 'logs' and 'spec' are documented, but 'request' and 'response' have no schema description at all. The description merely echoes those two names without saying what form they take (raw HTTP text, curl, JSON envelope) or how 'spec' affects diagnosis, so it fails to compensate for the gap.

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 concrete verb pair and resource: take a request/response/logs and 'name the likely cause and a fix' for an API/integration failure. That is distinguishable from nearby siblings like fikra_analyse_logs or fikra_debug_sql. It stops short of a crisp one-line definition because the trailing fragment 'Debugging an integration failure quickly' restates the use case rather than sharpening scope.

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

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

The phrase 'Debugging an integration failure quickly' implies when to reach for it, but there is no explicit when-not or routing to alternatives such as fikra_analyse_logs, fikra_analyse_openapi_spec, or fikra_generate_api_tests, which plausibly overlap. Usage is inferable rather than 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 declare readOnlyHint=false and idempotentHint=false, yet the tool is described as a pure price lookup; the description never explains why a cost estimate might mutate anything or whether the estimate is binding/charged. It also contradicts itself on pricing behaviour ('live rate card' vs 'Fixed price $0.01 per call'), which leaves the agent unsure whether cost varies with model or tokens. No permission, rate-limit, or billing context is given.

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 very short sentences with no filler, but the final sentence is a fragment that restates the second and adds no actionable information. Sizing is fine; ordering mixes the mechanism (rate card) with a flat price before the usage hint.

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, no annotation-level detail, and 0% schema description coverage on three parameters, the description should explain the return value (total cost? breakdown?) and the meaning of model/token inputs. It does neither, and its fixed-price assertion conflicts with the parameter set, leaving an agent unable to call it confidently.

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

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

Schema description coverage is 0% across three parameters, so the description must carry the load and does not: it never explains what 'model' should contain (a model id from fikra_list_models?) or what units/format input_tokens and output_tokens take as strings. Worse, the claim of a fixed $0.01 per call suggests the token parameters are irrelevant, which is actively confusing about how cost is computed.

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: estimate the cost of a planned inference call. An agent can distinguish it from generation/analysis siblings such as fikra_compare_models or fikra_list_models. It stops short of distinguishing it from the other pricing/quoting siblings (fikra_quote, fikra_get_tool_prices), so it is clear but not fully differentiated.

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 'Knowing the price before running a job' implies the when: check cost ahead of execution. There is no explicit alternative named (e.g. use fikra_quote for job-level pricing or fikra_get_tool_prices for the catalogue) and no statement of when not to use it, so usage is only 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?

The annotations already declare the safety profile (destructiveHint=false, openWorldHint=false), so the description needn't restate that. It does add one genuinely valuable trait not in structured data: a fixed price of $0.01 per call, which matters for a metered tool. However it says nothing about output shape, latency, or payload size limits, so the behavioral picture is incomplete. Note the annotations set readOnlyHint=false for what is plainly an analysis-only tool, but the description doesn't contradict them, so no contradiction flag.

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, front-loaded sentences with no filler; the core purpose leads. The trailing fragment ('Understanding a third-party response quickly.') is slightly clipped and would read better merged into the first sentence, 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?

No output schema exists, so the description is the only place an agent can learn what comes back — and it doesn't say. Combined with 0% parameter coverage and an unexplained `context` argument, an agent knows the gist but not how to call it well or what to expect in return.

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

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

Schema description coverage is 0% for both parameters, so the description must compensate and it does not. The required `json` parameter is only obliquely implied by 'JSON payload field by field', and the optional `context` parameter is never mentioned at all — an agent has no idea what to put there or why it would help.

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 gives a specific verb ('Explain') and a specific resource ('an unfamiliar JSON payload'), plus the granularity ('field by field'). That is clearly distinct from every sibling, none of which is a JSON explainer. It only stops short of a 5 because it doesn't name the nearest alternatives (e.g. fikra_extract_invoice_fields or fikra_analyse_openapi_spec) that an agent might confuse it with.

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?

'Understanding a third-party response quickly' implies the situation (an unfamiliar external payload you need to interpret), so usage is inferable. But there is no explicit when-not guidance, no mention of alternatives, and no prerequisite information about what kind of JSON it handles or its size limits.

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 destructiveHint=false and openWorldHint=false but readOnlyHint=false and idempotentHint=false, so an agent cannot tell from them alone why this extraction call is non-read-only. The description adds a genuinely valuable behavioral fact — a flat $0.15 per call charge, which explains the non-idempotent billing — but says nothing about input length limits, what happens when a requested date is absent from the document, or the shape of 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?

The purpose is correctly front-loaded in the first sentence and the price is worth keeping, but the third sentence is pure marketing filler that consumes a third of the description without informing tool selection or invocation. Two of three sentences earn their 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 carries responsibility for return-value disclosure; the enumerated date types partially cover this by implying the returned fields. However, an agent still cannot tell the result format, whether dates are normalized, or how missing dates are reported — material gaps for an extraction tool with no output schema.

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

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

Only one parameter exists and the schema documents it at 100% coverage ('Document text to process'), so the schema does the heavy lifting. The description adds no further semantics about expected input format, size, or whether pre-extracted text vs. raw file content is accepted.

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 (pull) and enumerates the exact resource fields retrieved: effective, expiry, renewal and notice dates. This field list distinguishes it from fikra_extract_contract_obligations, fikra_summarise_contract and fikra_analyse_contract_risks without needing to open 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?

There is no explicit when-to-use, when-not, or alternative-tool routing — nothing tells the agent to prefer this over summarise_contract or analyse_contract_risks. The closing slogan ('Never missing a renewal or notice window again') gestures at a renewal-tracking use case but is marketing copy rather than 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 disclose readOnly=false, idempotent=false, destructive=false, and the description adds a genuinely useful behavioral fact not in any structured field: a fixed price of $0.50 per call. It stops short of describing the output shape or what happens with malformed/long documents, which matter for an extraction tool with no output 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 short sentences with no filler; the substantive purpose is front-loaded. Minor redundancy between sentence one and sentence three, and the pricing sentence interrupts the flow, 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?

The tool is simple (one fully documented parameter), and purpose plus cost are covered. Still, with no output schema, an agent gets no sense of the return structure (per-party grouping? list of obligation/deadline/payment entries?), which is the main remaining gap for calling 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?

Only one parameter exists and the schema descriptions cover 100% of it ('Document text to process.'). The description adds no constraint on document length, format, or whether raw text vs. markdown is expected, so it matches the baseline rather than exceeding it.

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: extract each party's obligations, deadlines and payment duties from a contract. The phrasing 'checklist of what must happen and when' further distinguishes it from summary-oriented siblings like fikra_summarise_contract, though it never names those siblings 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 clause 'Turning a contract into a checklist of what must happen and when' implies the use case (post-signature tracking of duties). It gives no explicit when-not guidance and does not route the agent to alternatives such as fikra_extract_contract_dates or fikra_summarise_contract.

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

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

With no annotations, the description carries the full burden. It does add two useful behavioral facts: a no-hallucination constraint ('No invented values') and an explicit cost of $0.25 per call, which lets an agent weigh invocation. It omits reliability details such as handling of long or malformed documents, failure modes, and what gets returned when fields are absent.

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

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

Three terse sentences, front-loaded with the core action, then the accuracy constraint, then the price. Nothing redundant or 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?

There is no output schema, so the description is the only place the return shape could be described, yet it only says 'structured JSON' without naming the extracted fields. For an extraction tool that is the single most decision-relevant missing detail, alongside input size/format expectations.

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?

Single required parameter with 100% schema description coverage ('Invoice or receipt text'), so the schema already defines it fully. The description adds no meaning beyond that but has nothing left to clarify, matching the baseline for well-documented single-param tools.

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?

Declares a specific verb (extract) and resource (invoice or receipt fields) with a concrete output form (structured JSON). The document types named make it clearly distinct from siblings like fikra_summarise_contract or fikra_screen_cv, though it never explicitly contrasts 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?

No statement of when to choose this over the sibling extraction/summary tools, no prerequisites, and no guidance on unsupported input (e.g. what happens if the text is not an invoice). Usage is only inferable from the named document types.

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 openWorldHint=false, so the safety profile is largely covered. The description adds genuinely non-structural behavior: a fixed $0.10 per-call price and a promise that output is "small and predictable," which explains the non-read-only hint (billing) and sets expectations about result size.

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, no filler, with the output-scope claim front-loaded. The final sentence is a dangling fragment that reads as notes rather than instruction, which keeps it from a 5.

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 is the only source of return-value information, and it says only "core invoice fields" without enumerating them or indicating confidence/error behavior. The pricing disclosure is helpful, but an agent still cannot anticipate what it will receive from a paid extraction 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?

There is a single parameter, `document`, and schema description coverage is 100%, so the schema already does the work. The description adds no detail on expected input format (raw OCR text vs. structured text, size limits), 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?

The verb/resource pair ("return only the core invoice fields") is present, but "core fields" is never defined and the definition does nothing to separate this from close siblings such as fikra_extract_invoice, fikra_process_invoice, or fikra_extract_purchase_order. An agent can tell it extracts something invoice-related, but not precisely how it differs.

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 only usage signal is the fragment "Feeding a fixed schema into an accounting pipeline," which hints at a downstream consumer but gives no when-to-use/when-not guidance and never names an alternative among the many extraction siblings. Nothing tells an agent why it would pick this over fikra_extract_invoice.

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

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

The description adds genuinely useful context beyond annotations by disclosing a fixed price of $0.10 per call, which an agent cannot derive from structured fields. However, it says nothing about how the 'structured requirements' are shaped, whether the input is validated/truncated, or what happens on a malformed posting — gaps that matter since there is no output 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 short, front-loaded fragments with zero filler. The trailing fragment ('Building a screening checklist from a posting') is a noun phrase without a verb, which reads slightly disjointed but is not verbose.

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-input extraction tool with no output schema and no parameter documentation, the description should at least sketch what the returned structure contains. It gives purpose and price but leaves the output shape entirely to 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?

There is a single required parameter with 0% schema description coverage, so the description carries the load. It implies the parameter is the raw job description text but adds no detail on format, length limits, or accepted input types.

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

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

The first sentence states a specific verb and resource ('Turn a job description into structured requirements'), which is clearly distinct from siblings like fikra_generate_job_description (the inverse) or fikra_screen_cv. It stops short of naming those siblings explicitly, so it lands at a clear-but-undifferentiated 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?

'Building a screening checklist from a posting' hints at a downstream use case, implying when the tool is appropriate, but there is no explicit when-to-use/when-not guidance or named alternative. Usage is inferable rather than 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?

The description adds useful behavioral context beyond annotations by disclosing a fixed price of $0.10 per call and by clarifying that the output is limited to action items and owners. Annotations already cover the safety profile, so this is a strong additional contribution even though return formatting is not described.

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 short and front-loaded, with the main purpose stated first and pricing disclosed immediately after. The final sentence is somewhat fragmentary but still contributes a usage cue without excess wording.

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 description is adequate for a simple extraction tool and usefully discloses pricing, but it lacks detail about the return format for the extracted action items and owners. Since there is no output schema, the agent has to infer what the result looks like.

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

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

The single parameter is obviously the transcript, and the description confirms it is the input source. However, with 0% schema description coverage, the description does not add any details about transcript format, size limits, or expected structure, leaving the schema to carry almost nothing.

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: extracting action items and owners from a transcript. The phrase "only the action items and owners" distinguishes it from broader meeting summarization or minutes-generation siblings, though it does not name 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 phrase "Following up after a call" implies a usage context, but there is no explicit guidance on when to choose this over siblings like fikra_extract_tasks or fikra_generate_meeting_minutes. The agent must infer the appropriate situation from the description alone.

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 (non-read-only, non-destructive, non-idempotent, closed-world), so the description's burden is lower. It adds genuinely new behavioral information not present in structured data: a fixed price of $0.20 per call, which matters for a paid, non-idempotent tool. It stops short of describing failure modes or limits on input size.

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 with the core capability front-loaded and the cost disclosure early. The trailing use-case sentence is slightly fragmentary grammatically but is short and adds contextual value rather than 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 single-string-input tool with no output schema, the enumeration of extracted fields effectively communicates the expected return shape, and the price is disclosed. Only minor gaps remain (input format/size expectations, behavior on unparseable documents).

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?

There is a single parameter with 100% schema description coverage ('Document text to process.'), so the schema already carries the semantics and baseline 3 applies. The description's list of extracted fields adds context about what the tool reads from the document but does not elaborate on the 'document' parameter itself.

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

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

The description uses a specific verb ('Extract') and resource ('purchase order') and enumerates the fields it pulls out (buyer, supplier, items, quantities, terms). An agent can tell this apart from fikra_compare_purchase_orders (comparison) and fikra_extract_invoice (different document type), though the description never explicitly names those alternatives.

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 'Getting PO data into procurement or ERP systems' implies a usage context but does not say when to choose this over siblings like fikra_compare_purchase_orders or fikra_generate_procurement_report, nor any prerequisites or exclusions. Usage is inferable rather than 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 non-destructive, non-idempotent, closed-world behavior, so the safety profile is covered. The description adds one genuinely useful operational fact, the fixed $0.05 per-call price, which the agent cannot get from structured fields. It says nothing about output shape, chunk/size limits on notes, or failure behavior on unusable input.

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 sentence is well front-loaded and the pricing note earns its place. The trailing "Getting from messy notes to a checklist." restates the first sentence in vaguer words and is pure 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?

With no output schema, the description is the only place an agent can learn what comes back, and it never says (list of task objects? owners as strings or inferred names?). Combined with 0% parameter coverage and an ambiguous optional parameter, the definition leaves the agent guessing on both sides of the 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 0% across two parameters, so the description must compensate and does not. It never explains what "notes" should contain (raw transcript? bullet list? length limits?) or what "context" is for (audience, project, date reference) despite "context" being an ambiguous, easily misused field.

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?

"Turn notes into a task list with owners and due dates" names a specific input (notes), a specific artifact (task list), and its fields (owners, due dates). That is enough to separate it from analysis tools like fikra_analyse_logs, though it does not explicitly distinguish it from the very similar fikra_extract_meeting_actions or fikra_organise_notes.

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 indication of when to reach for this instead of fikra_extract_meeting_actions (also an extraction-from-text tool) or fikra_organise_notes. No preconditions, no exclusions, no 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 already declare non-readOnly, non-destructive, non-idempotent and closed-world, so safety is covered. The description adds genuinely new context—a fixed $0.02 per-call price—which the agent cannot get from structured fields. It still omits how many variants are returned and whether output is deterministic, given idempotentHint=false.

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 with the purpose front-loaded and the price in the middle; nothing is redundant. It is appropriately sized for the amount of information it chooses to convey.

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 should explain the return shape (how many variants, approximate length, format), but it does not. Combined with fully undocumented parameters and no sibling routing, an agent has to guess at both inputs and outputs before calling a paid 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 0% across three parameters, so the description carries the full burden. It only implies that 'product' is the input; 'tone' and 'audience' are never mentioned, and no guidance on acceptable values or defaults is given. With zero schema help, this is a clear gap.

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: 'write short ad copy variants for a product.' The agent can tell this is a creative copy-generation tool. It does not name a sibling to distinguish itself from near-neighbours like fikra_generate_social_post or fikra_generate_product_description, leaving the boundary 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?

'Several options to test without starting from a blank page' implies the use case is variant generation for A/B testing, but the description never says when to prefer this over the other generate_* siblings or when it's the wrong choice. Usage is implied rather than 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 establish that this is not read-only, not destructive, not idempotent, and closed-world. The description adds useful cost context ('$0.05 per call') but does not explain output format, whether tests are returned or written somewhere, or how the spec is consumed.

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 only three short sentences and is front-loaded with the core action. The pricing and value sentences are relevant, though the final sentence is slightly promotional rather than operational.

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 do more to explain what the agent gets back, such as generated test code, file artifacts, or a report. It is adequate for a simple two-parameter generation tool but leaves meaningful gaps around output and spec format.

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 50%: framework is described in the schema, but spec is not. The description clarifies that spec is an OpenAPI document, adding some value, but it does not mention the optional framework parameter or accepted spec formats such as JSON or YAML.

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: producing test cases from an OpenAPI document. This distinguishes it reasonably well from generic unit-test generation and OpenAPI analysis siblings, though it does not explicitly name alternatives.

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 'A starting test suite instead of hand-writing every case' implies when to use it, but there are no explicit when-not conditions, prerequisites, or named alternatives such as fikra_generate_unit_tests or fikra_analyse_openapi_spec.

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-destructive, non-open-world, non-idempotent write-side operation, so the safety profile is covered. The description adds genuinely useful undisclosed context: the fixed $0.30 per-call price and that output is produced 'in one pass' (no iterative refinement or follow-up calls). It stops short of describing latency, failure/refund behaviour, or what the returned 'structured proposal' actually contains.

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 fragments with the core action front-loaded and no filler; cost information is placed where it is easy to scan. The trailing sentence 'A structured proposal in one pass' repeats the deliverable and is the weakest of the three, but it is not long enough to be 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?

There is no output schema, so the description is the only source of return-value information, and 'a structured proposal' is too vague to set expectations about sections, length, or format. Pricing and the single-pass semantics are disclosed, but the undocumented 'client' parameter and the unspecified output shape leave real gaps for a paid generation 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 0%, so the description must carry the parameter burden and it largely does not. It hints that 'brief' is the source text, but says nothing about its expected content, length, or format, and the optional 'client' parameter is never mentioned at all — an agent cannot tell whether it is a client name, ID, or free-text context.

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

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

Names a specific verb and artifact ('Draft a proposal') and the input it derives from ('from a brief'), so the agent understands it synthesises a proposal document rather than analysing one. It never explicitly contrasts itself with nearby siblings like fikra_generate_business_quote or fikra_generate_business_report, leaving the agent to infer which artifact type it wants.

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 statement of when to choose this over fikra_generate_business_quote or fikra_generate_business_report, no prerequisite guidance, and no exclusions. The only usage signal is the implied 'you need a brief', which is already enforced by the required parameter in the schema.

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

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

Annotations already establish that this is a non-readonly, non-idempotent, non-destructive operation. The description adds useful context by disclosing the fixed cost of $0.15 per call and that output is generated without a template. It does not describe the return format, permissions, or what happens if the brief is insufficient, which keeps it at an adequate but incomplete level.

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 short and front-loads the purpose and cost. The third sentence, 'Sending a clear quote without a template', is awkward and offers little actionable meaning, so not every sentence earns its place.

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

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

There is no output schema, and the description does not explain what the generated quote looks like or how the currency should be supplied. With two undocumented parameters and no output description, the definition leaves important gaps for an agent trying 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 0%, so the description must carry the burden of explaining 'brief' and 'currency'. It does not: 'brief' is never defined, and 'currency' is never mentioned, leaving ambiguity about whether currency is an ISO code, a symbol, or free text. The domain context loosely implies both fields but does not provide usable semantics.

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 gives a specific verb and resource: 'Write a priced quote for a client.' That is clear enough to identify the operation. However, it does not distinguish this tool from siblings like fikra_quote or fikra_compare_quotations, so the agent must infer the difference 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?

There is no explicit when-to-use guidance or comparison to alternatives. 'Sending a clear quote without a template' describes a mode of operation rather than a selection condition, and it never says when an agent should prefer this over fikra_quote or another generation tool.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation/idempotency profile is covered. The description adds genuinely useful non-annotation context: a fixed $0.50 per-call cost, which matters for an agent deciding whether to invoke. It says nothing about latency, output format, or what happens on partial/unsupported documents.

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 with the purpose front-loaded, but the third sentence ('A single report from invoices, contracts and notes') largely restates the first, and the pricing sentence is inserted mid-flow rather than after the operational facts. Compact, but one sentence does not earn 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?

There is no output schema, so the description should explain what 'structured report' actually contains (sections, fields, format) — it does not. Combined with the undocumented 'documents' element format and no note on how many documents are accepted, an agent lacks the information needed to invoke this reliably.

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 50%: 'focus' is documented in the schema, but the required 'documents' array has no description at all. The description hints at content types (invoices, contracts, notes) but never states the expected element format — file paths, URLs, or raw text — which is the single most important thing an agent must know to call this correctly.

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 ('Turn several business documents into a structured report'), which is far clearer than a name restatement. However, it never distinguishes itself from close siblings such as fikra_generate_procurement_report or fikra_generate_expense_report, so an agent cannot tell which report generator to pick from purpose 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?

'Turn several business documents into...' and 'A single report from invoices, contracts and notes' imply the use case (multi-document synthesis rather than single-document extraction). There is no explicit when-to-use/when-not guidance and no named alternative for narrower report 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 the mutation/idempotency/safety profile, so the bar is lower. The description does add genuinely new information the annotations lack — a fixed $0.15 per-call cost — plus a grounding claim ('real experience'), but it omits length limits, output shape, and any auth/quota 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?

Three short sentences, front-loaded with the core action, and the price is stated plainly. The closing 'specific letter instead of a generic template' is mild marketing padding rather than operational 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 no annotations describing returns, the description should indicate what comes back (format, rough length, structure). It covers cost and input intent but leaves the agent guessing about the deliverable, which is a meaningful gap for a generation 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?

Both required parameters (cv, job_description) have 0% schema description coverage, so the description must carry their semantics and does not — it never mentions them by name, nor their format, size, or whether cv is raw text or structured. 'Grounded in the candidate's real experience' only vaguely gestures at the cv input.

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-plus-resource is specific: 'Draft a cover letter' scoped to 'the candidate's real experience' clearly separates it from siblings like fikra_tailor_cv or fikra_generate_job_description. It stops short of explicitly naming the nearest alternative, so it is clear but not fully differentiated.

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 usage context (a candidate with a CV applying to a job) but never states when to choose this over fikra_tailor_cv or fikra_generate_customer_response, nor any exclusions. 'A specific letter instead of a generic template' is a selling point, not 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?

The annotations already declare this is a non-readonly, non-destructive, non-idempotent, closed-world operation. The description adds the useful fixed price of $0.03 per call and frames the output as a fast reply, but it does not explain that repeated calls may produce different results, what format the reply takes, or any limits. It adds some context beyond annotations but leaves meaningful behavioral gaps.

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 short, front-loaded, and easy to scan. However, 'Fast, on-brand replies' is promotional rather than operational, and that space could have been used to document the tone parameter or output 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?

There is no output schema and no parameter documentation, so the agent must rely entirely on the description. The description does not state what the reply looks like, how tone affects the result, or how the required message is used. Given the tool's generative nature and the undocumented parameters, it is materially 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 0%, so the description must carry the burden for the two parameters. It implies that 'message' is the customer message to reply to, but it says nothing about 'tone' or what valid tone values might be. For a tool with zero schema documentation, this is insufficient.

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: 'Write a reply to a customer message.' That is clear enough to understand the operation. It does not distinguish itself from sibling tools that also involve customer messages, such as fikra_process_customer_complaint or fikra_chat, so it stops just short of a 5.

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 no guidance on when to use this tool rather than alternatives like fikra_process_customer_complaint, fikra_chat, or fikra_generate_social_post. There are no exclusions, prerequisites, or routing conditions.

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 flat '$0.30 per call' pricing is genuinely useful disclosure for an agent deciding whether to call a paid endpoint, and it goes beyond what the annotations declare. However, the description says nothing about output format, size limits on the input document, or how large receipt batches are handled; annotations only cover the safety profile (non-read-only, non-destructive, 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 short sentences, front-loaded with the actual capability, then price, then audience. The third sentence largely restates the first ('A clean expense summary') and is the only real 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?

There is no output schema, so the description should say more about what comes back — structure, level of detail, or whether periods are inferred or must be present in the document text. With one fully documented parameter and annotations present, this is adequate but leaves a real gap for a generation 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% for the single 'document' parameter, so the schema already carries the load and a baseline 3 applies. The description adds that output is grouped by category and period, but gives no hint about expected input format (free text vs. structured rows) or practical size constraints.

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

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

States a specific verb and resource plus the aggregation dimensions ('Summarise expenses by category and period'), which is far better than a tautology. It does not distinguish itself from near-siblings such as fikra_categorise_expenses or fikra_generate_procurement_report, so an 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?

The audience note ('for a manager or accountant') implies a downstream-consumer use case, but there is no explicit when-to-use, no when-not-to-use, and no named alternative. Nothing tells an agent whether to categorise first with fikra_categorise_expenses or whether raw receipts belong in fikra_process_receipt.

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 a non-read-only, non-destructive, non-idempotent, closed-world generation call, so the safety profile is covered. The description adds genuinely useful non-schema context — a fixed $0.15 per-call cost — which matters for a non-idempotent tool an agent might otherwise retry. It stops short of describing output shape, question count, or generation behaviour.

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 and the cost disclosure are efficient and earn their place. However, the trailing "Preparing a structured interview." is a dangling fragment with no subject or verb, costing a sentence without adding guidance.

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 and no annotations describing returns, yet the description says nothing about what comes back (number of questions, format, structure), how the two inputs shape output, or whether the call is repeatable given idempotentHint=false. For a paid generation tool with two undocumented required params, this leaves real 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 0% and both parameters are required with no descriptions. The word "role-specific" loosely maps to `role`, but `requirements` — the more ambiguous input — is never explained (free text? extracted from a job ad? how detailed?). The description does not compensate for the coverage gap.

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?

A specific verb+resource pair ("Produce ... interview questions") with a scoping qualifier ("role-specific"). It is clearly distinct from closest siblings like fikra_generate_job_description, fikra_screen_cv, or fikra_compare_candidates, but the description never names or excludes any of 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?

"Preparing a structured interview" implies the usage context but is a sentence fragment offering no when/when-not guidance and no alternatives. An agent can infer the scenario but must guess whether e.g. fikra_extract_job_requirements should be called first to build the `requirements` input.

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, destructiveHint=false, openWorldHint=false, idempotentHint=false), so the description only needs to add beyond that. It does contribute one genuinely non-redundant fact — a fixed $0.15 per-call cost — but says nothing about output length/format or that repeated calls are non-idempotent, which matters given idempotentHint=false.

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?

It is short and front-loads the core action in the first sentence, with pricing second. The trailing "Writing a clear posting quickly" is a marketing tagline that does not help an agent decide or invoke and could be dropped.

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 two-parameter generation tool this covers the essentials, but with no output schema the description should hint at what comes back (length, structure, whether tone is respected). It also omits that results vary between calls, consistent with idempotentHint=false.

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 are already documented; baseline is 3. The description's "from a short brief" adds a soft hint about desired brevity of the brief but gives no detail on tone usage or expected brief structure.

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?

"Draft a job description from a short brief" gives a specific verb (draft) and resource (job description) plus the required input, so it is distinguishable from nearby siblings like fikra_extract_job_requirements or fikra_generate_interview_questions. It stops short of explicitly naming which sibling to prefer for adjacent hiring tasks.

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 statement of when to use this versus alternatives (e.g. extract vs generate job content) and no preconditions beyond "short brief". The remaining sentences are about price and a vague benefit claim, not selection 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 this is a non-read-only, non-idempotent, non-destructive open-world-free call, so the safety profile is covered. The description adds a genuinely useful trait not in structured data: a fixed $0.20 charge per call. It does not disclose transcript length limits, output verbosity, or whether each call re-bills, which matters for a non-idempotent paid 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 short sentences, front-loaded with the core transformation and pricing. The final fragment ("Writing up a meeting without listening again") is marketing-flavoured and carries less information than the space it occupies, but nothing is seriously bloated.

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 two-parameter generation tool with no output schema, the description covers what comes back at a high level (minutes, decisions, action items) and the cost. It is incomplete on the undocumented context parameter and on practical limits of the transcript input, which an agent needs before invoking a paid, non-idempotent 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 0%, so the description must compensate for both parameters. It only implies the role of "transcript"; the optional "context" parameter is never mentioned, leaving an agent to guess what it is for and what to put in it.

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 transformation: turn a transcript into minutes, decisions and action items. The output fields are concrete enough to distinguish it from generic summarisation tools. It never names the closest sibling, fikra_extract_meeting_actions, which overlaps on the action-items output.

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 tagline "Writing up a meeting without listening again" implies the use case (you already have a transcript and want minutes), but usage is left implicit. There is no explicit statement about when to prefer fikra_extract_meeting_actions or fikra_summarise_audio instead, which are the obvious alternatives.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation profile is covered; the description adds genuinely useful non-schema context: a fixed price of $0.50 per call. It does not disclose the output shape, whether the report is persisted, or any failure modes for mixed/incompatible documents.

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 with the core action and the cost up front. The final sentence is a sentence fragment that adds little beyond the first, but nothing is padded or buried.

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, and the description does not describe the report's contents or format. Combined with the undefined required 'documents' parameter, an agent cannot reliably assemble a valid call from this definition 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?

With 50% schema coverage, the burden falls on the description, and it does not compensate. The required 'documents' array has no description in the schema and the description never says what the items should be (document IDs, file contents, extracted text) or whether quotes and POs must be supplied together.

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 first sentence gives a specific verb ('Combine') and resources ('quotes and POs') with the output artifact named ('decision-ready report'), which separates it from siblings like fikra_compare_purchase_orders and fikra_analyse_supplier_quotes. The trailing fragment 'Presenting a sourcing decision with the numbers and the caveats' restates purpose rather than extending it, and it does not explicitly name the sibling it replaces.

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?

'Presenting a sourcing decision with the numbers and the caveats' gestures at the use case (sourcing decisions) but never states when to pick this over fikra_compare_purchase_orders, fikra_analyse_supplier_quotes, or fikra_generate_business_report. The need to supply quotes AND POs together is implied but not called out as a precondition.

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-read-only, non-destructive, non-idempotent call, so the mutation profile is covered. The description adds genuinely useful context beyond that: a fixed price of $0.03 per call, which lets an agent reason about cost. It still omits rate limits, auth requirements, and whether repeated calls produce different copy.

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 with the cost disclosed early. The final clause ('Listing a product without rewriting copy each time') is slightly awkward but not 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?

With no output schema and 0% schema coverage, the description should explain what comes back (length, number of variants, format) and what the parameters mean. It hints at 'short variants' but leaves parameter semantics and return shape substantially 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 0%, so the description must carry parameter meaning, and it largely does not. The required 'product' param is only implied by the verb, and the optional 'audience' param is never mentioned at all, leaving its format and effect unknown.

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 ('Write a product description and short variants'), which is clearly distinct from siblings like fikra_generate_ad_copy or fikra_generate_social_post. It does not explicitly name an alternative, but the resource is specific enough to route correctly.

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 'Listing a product without rewriting copy each time' implies a scenario (bulk/listing workflows) but gives no explicit when-to-use/when-not-to-use criteria or named alternatives. Usage is inferable rather than 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 this is a non-read-only, non-idempotent, non-destructive call, so the safety profile is covered. The description adds genuinely useful pricing context ('Fixed price $0.05 per call') and clarifies that two artifacts are produced per call, but says nothing about whether a failed/retried call is billed again, output length, or formatting.

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 short sentences are front-loaded with the core purpose, which is good. The trailing fragment 'Keeping a consistent posting cadence' is vague and reads as marketing filler rather than instruction, using space without adding actionable meaning.

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

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

With no output schema, zero schema descriptions, and no parameter guidance, an agent cannot tell what tones or platforms are valid or what shape the post/thread will take. The pricing note helps, but the definition is well short of what a 3-parameter generative tool needs.

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

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

Schema description coverage is 0% across three parameters, so the description carries the full burden and mostly fails. 'One idea' loosely maps to topic, but neither tone nor platform is explained — no allowed values, no defaults, no effect on output.

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 verb and output pair: write a social post and a short thread from one idea. That distinguishes it reasonably from the analysis/extraction siblings, though it does not explicitly separate it from fikra_generate_ad_copy or fikra_generate_product_description, which are its nearest neighbors.

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 or when-not-to-use guidance. The only contextual line, 'Keeping a consistent posting cadence,' gestures at a use case but never tells the agent why it should pick this over generate_ad_copy or how platform/tone choices should drive 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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely useful context beyond that: a fixed $0.10 per-call price, which matters for a paid generation endpoint. It does not say what comes back (test code block, file, prose) or how long generation takes.

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 with the core purpose front-loaded and no bloat. The closing 'Coverage without the setup cost' is marketing filler that does not earn its place, but it costs little.

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 no per-parameter documentation, the description should say more about the return value and about the optional language/framework inputs. The annotations cover the safety profile and the price is disclosed, so the minimum is met, but an agent still cannot tell what it receives back.

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

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

Schema description coverage is 0%, so all three parameters (code, language, framework) are bare. The phrase 'for a function or module' loosely hints at the `code` input, but `language` and `framework` are never mentioned, and nothing says whether they can be inferred or defaulted.

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 artifact: 'Write unit tests for a function or module.' An agent immediately knows the operation. However, it does not distinguish itself from the close sibling fikra_generate_api_tests, which an agent could easily confuse with 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?

There is no when-to-use guidance, no exclusions, and no mention of the closely related fikra_generate_api_tests or fikra_review_code alternatives. 'Coverage without the setup cost' is marketing copy, not a usage condition.

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 "$0.10 per call" disclosure is genuinely useful added context: combined with idempotentHint=false it tells the agent that retries and re-calls cost real money. However, nothing describes output form, supported lengths, or failure handling. With annotations already covering the safety profile (non-destructive, closed-world), this earns a middle score rather than high marks.

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 compact sentences with the capability stated first and pricing second; no filler. Slight deduction for the third sentence reading as a fragment that partly repeats the first rather than adding new 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?

For a paid, non-idempotent generation tool with zero schema coverage and no output schema, the description omits how long the script will be, how `duration_seconds` affects it, what a 'brief' needs to contain, and what the returned structure looks like. "Scene beats" hints at the format but does not specify it.

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

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

Schema description coverage is 0%, so the description must compensate and does not: it never explains what belongs in `brief`, nor what `duration_seconds` accepts — notably a string type with no format or examples, which is a real ambiguity. Only the name 'brief' carries any self-evident meaning, and the description's "short" is the sole, unquantified length signal.

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

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

Specific verb+resource ("Write a short video script") plus the output shape ("with scene beats"), which separates it from the many other fikra_generate_* siblings such as generate_ad_copy or generate_social_post. It does not explicitly name which sibling to use instead for adjacent needs (e.g., social post vs. video script), so it stops short of a 5.

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 only contextual hint is the trailing phrase "for a product or explainer video," which characterizes the domain but gives no when-to-use/when-not-to-use rules, no prerequisites, and no named alternatives among the ~20 other generate_* tools. An agent must infer selection from the name alone.

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

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

No annotations exist, so the description carries the full disclosure burden. 'Return' implies a read-only operation, 'masked email' discloses a privacy behavior, and 'Free' discloses cost — genuinely useful context beyond the name. It stops short of stating auth requirements or what happens when the caller is unauthenticated.

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?

One sentence, zero waste, front-loaded with the action and resource. The return fields and the cost note are packed in without 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 usefully enumerates the returned fields (masked email, balance, scopes) and notes the call is free. Nothing more is needed for such a simple zero-param read, though an error/auth note would make it airtight.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly conveys that no input is needed, matching the empty schema.

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

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

The description states a specific verb ('Return') and resource ('the authenticated account') and enumerates the content returned: masked email, balance, scopes. It is clear what the tool does, but it does not differentiate itself from the sibling fikra_get_balance, which overlaps on the balance field.

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 call this versus fikra_get_balance, fikra_get_usage, or fikra_list_api_keys, all of which are sibling read tools on the same account domain. The only usage-adjacent signal is 'Free', which hints at cost but does not route the agent between 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the operation is a read and is free (no credit consumption), which is genuine behavioral context for a metered API, but says nothing about auth requirements, whether the balance is cached, or what happens for an unfunded wallet.

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 short sentences, zero filler, with the core operation stated first and the cost hint appended. Every clause 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?

For a no-param read with no output schema and no annotations, the definition covers what is returned (wallet balance) and in what unit (USD). It stops short of describing the response shape or auth prerequisites, which would be the remaining value-add.

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-parameter tool, so baseline 4 applies. The description correctly signals no inputs are needed and pins the output unit to USD, which is the only semantic detail that matters here.

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 ('Return the wallet balance') plus the unit (USD), which is more than a restatement of the name. It does not distinguish itself from adjacent reads like fikra_get_account or fikra_get_usage, so an agent must infer the split.

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 'Free' hints that calling this costs no credits, which is implicit guidance, but there is no statement of when to prefer this over fikra_get_account (balance vs. account details) or fikra_get_usage. Usage is implied rather than 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?

With no annotations, the description carries the full burden, and it only discloses that the call is free. It says nothing about whether the receipt must already exist, what happens on an unknown or not-yet-complete request id, whether results expire, or whether any authentication/ownership applies.

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 short sentences with the operation front-loaded and no padding. The brevity is close to under-specified, but nothing written 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 fetch tool with zero annotations, no output schema, and an undocumented required parameter, the description should explain the async/retrieval relationship to fikra_process_receipt and what a receipt result contains. Neither is covered, leaving an agent to guess at the calling pattern.

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

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

Schema coverage is 0%, so the description must compensate. It does add one useful clue by describing receipt_id as a 'request id', implying the identifier comes from a prior processing request rather than a plain document id, but it gives no format, source, or example for the value.

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 ('Read a receipt') plus the lookup key ('by request id'), so the basic operation is unambiguous. It does not, however, differentiate itself from siblings such as fikra_process_receipt or fikra_extract_invoice, so an agent must infer that this is a retrieval/fetch step rather than a new extraction.

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 statement of when to use this tool versus fikra_process_receipt, nor any note about calling it after a processing request. The only guidance offered is the cost note 'Free.', which addresses pricing, not 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?

With no annotations, the description does carry the full load, and it does disclose two useful traits: the listing is read-only ('List') and it costs nothing ('Free'), which matters on a credit-metered platform. It stops short of saying how large the catalog is, whether results are paginated, or what the entry shape looks like beyond 'inputs and price'.

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 short, front-loaded sentences with no filler; the scope ('every live fixed-price tool') arrives first. The clipped 'Free.' fragment is terse but does carry signal, 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?

For a simple, no-output-schema list tool the description covers what comes back ('inputs and price') and the cost profile, which is most of what's needed. It remains incomplete on the one input parameter and on result size/pagination 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 coverage is 0% and the single parameter 'category' is entirely undocumented, yet the description never mentions it. An agent cannot tell whether category filters the catalog, is required, or accepts a fixed vocabulary — the description fails to compensate for the schema gap.

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 specifies a verb ('List') and a concrete resource ('every live fixed-price tool') plus what each entry carries (inputs and price). It is clear on its own, but it does not differentiate itself from close siblings such as fikra_get_tool_prices, which an agent could easily confuse it with.

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 statement, no exclusion, and no named alternative. Given siblings fikra_get_tool_prices and fikra_list_models, the agent is left to infer that this one is the broader catalog rather than the price-only view.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the call is free ('No charge'), which is useful, but says nothing about read-only behavior, idempotency, return format, or whether any side effects exist.

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 short sentences and front-loads the core idea. However, 'Free' and 'No charge' are redundant, and the brevity comes at the cost of missing important 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?

With no output schema, the description should explain what the tool returns, such as a list of tools and their fixed prices. It does not, nor does it clarify how this differs from fikra_get_tool_catalog, leaving the agent with insufficient context to select it confidently.

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

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

The tool has zero parameters, so there is no parameter semantics to document. The baseline score of 4 applies because the schema is empty and the description does not need to compensate for missing parameter details.

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

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

The description says it performs 'price discovery for fixed-price tools,' which hints at returning prices, but 'price discovery' is vague and it never states the output or scope. It does not distinguish this tool from siblings like fikra_get_tool_catalog or fikra_estimate_inference_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?

There is no guidance on when to use this tool versus alternatives such as fikra_get_tool_catalog, fikra_get_balance, or fikra_estimate_inference_cost. The only implied usage is 'when you want prices,' which is not explicit.

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

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

With no annotations, the description carries the full burden and discloses only one trait: the call is free (no credit consumption). It says nothing about default row count, pagination, ordering, or what a 'usage row' contains, all of which an agent needs for a read-only accounting endpoint.

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 short sentences, front-loaded with the core action and no filler. It is efficient, though the brevity shades into under-specification rather than tight precision.

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 zero annotations, no output schema, and an undocumented parameter, the description leaves too much unresolved: no return shape, no default limit, no time window. A 'usage' concept especially needs a scope definition (per tool? per day?) that is entirely 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 0% for the single `limit` parameter, and the description never mentions it. Default behavior when `limit` is omitted (a 1–100 range with no documented default) is left entirely to inference.

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: 'Return recent usage rows for the account.' An agent can tell this is a read of usage data rather than balance or account metadata. It stops short of explicitly distinguishing itself from close siblings like fikra_get_balance or fikra_check_topup_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?

There is no statement of when to use this versus fikra_get_balance, fikra_get_account, or fikra_check_topup_status, and no exclusions or prerequisites. 'Recent' implies a recency filter but never defines the window. The only guidance-like signal is 'Free'.

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

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

With no annotations, the description carries the full disclosure burden. It does add real value by stating keys are returned 'without secrets' (an output-safety guarantee) and that the call is 'Free' (a cost trait). It omits auth/account-scoping requirements and whether results are paginated or 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?

A single compact sentence with the resource, the returned fields, the safety trait, and the cost trait front-loaded. 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?

No output schema exists, but the description enumerates the return fields (id, name, prefix, status, budgets), effectively standing in for one. For a zero-param read tool this is nearly complete, lacking only auth/pagination notes.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool is 4.

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 API keys for the account') and enumerates the returned fields, so the agent knows exactly what it gets. It doesn't explicitly distinguish itself from fikra_revoke_api_key or fikra_set_key_budget, but the verb makes the difference self-evident.

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 guidance or mention of alternatives such as fikra_get_account or fikra_get_usage. 'Free' faintly hints this is the cost-safe inspection path, but the agent must infer that on its own.

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

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

No annotations exist, so the description carries the burden; it does disclose the return content ('with prices') and cost ('Free'), which is meaningful for a zero-parameter tool. It does not say whether the list is exhaustive or ordered, so transparency is adequate but thin.

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 short, front-loaded sentences with no filler; the purpose leads and the cost note follows. The fragment 'Free.' is terse but earns its place by answering a likely agent question.

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 zero-parameter, no-output-schema discovery tool the definition is largely sufficient: it names the resource and the shape of the result (models plus prices). Minor omissions are ordering/exhaustiveness, which are unlikely to block correct invocation.

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

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

The schema has zero parameters, so there is nothing for the description to disambiguate. The baseline of 4 applies; 'with prices' adds a note about return content rather than parameter meaning.

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

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

States a specific verb ('List') and resource ('Fikra chat models') and adds an attributed detail ('with prices'). The sibling fikra_chat is distinct in kind (a chat action vs a discovery list), but the description never explicitly contrasts the two, so it stays below the 5 bar.

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?

'Free.' signals there is no cost barrier, which is usable context, but there is no explicit when-to-use statement or reference to fikra_chat as the follow-on action. Usage is implied by the list-models purpose rather than 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=false, destructiveHint=false and openWorldHint=false; the description adds the genuinely non-obvious detail that every call costs a fixed $0.05, which matters for an agent deciding whether to batch. It says nothing about input size limits, output shape, or whether the call is retry-safe (idempotentHint=false would be worth reinforcing).

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 the price sentence earns its place. However, the third sentence ("Making sense of unstructured notes") restates the purpose with no new information and could be cut.

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 no documentation of return structure, an agent cannot tell whether it gets a grouped list, a JSON object, or prose. Given a paid, non-idempotent, single-string input tool, the definition should at least sketch the expected output and input conventions.

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?

There is one required parameter (notes) with 0% schema description coverage, so the description carries the full burden — but it never says what belongs in the string, expected length, formatting, or whether multiple notes should be delimited. Only the verb "group" hints at the input being a collection.

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?

"Group notes into themes and next steps" gives a concrete verb (group) and specific outputs (themes, next steps), which is more informative than the bare name. It is distinguishable from summarise_* or extract_tasks siblings, though it never explicitly contrasts 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?

No guidance on when to use this versus fikra_extract_tasks, fikra_generate_meeting_minutes, or fikra_summarise_research, all of which overlap in spirit. The closing line "Making sense of unstructured notes" is a tagline, not a usage condition.

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=false, destructive=false, idempotent=false and closed-world, so safety is covered structurally. The description adds genuinely useful context beyond them — the fixed $0.05 per-call price — but says nothing about what classification labels are produced, whether the response is a draft or sent output, or any limits.

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

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

The core action is front-loaded in the first sentence and the price note is compact. The fragment 'Handling support messages consistently' is filler that earns little, but total length is tight.

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 describe the return shape (what categories it classifies into, what the suggested response looks like), and it doesn't. Combined with the undocumented 'policy' parameter, an agent cannot invoke this reliably.

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

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

Schema description coverage is 0%, so the description must compensate — and it only implies that 'message' is the complaint. The 'policy' parameter (an optional string governing the response) is never explained anywhere, leaving an agent to guess how to populate it.

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 and resource: 'Classify a complaint and suggest a response.' An agent can tell it is a complaint-handling tool, though it doesn't distinguish itself from the nearby sibling fikra_generate_customer_response.

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, when-not-to-use, or alternative guidance. The trailing phrase 'Handling support messages consistently' gestures at a domain but does not tell the agent when to pick this over fikra_generate_customer_response or fikra_generate_business_report.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful pricing context ('Fixed price $0.25 per call') that appears nowhere in structured fields. It loses credit for claiming it turns a 'PDF' into fields while the schema only accepts 'Document text to process' — an agent may try to pass a file path or binary and fail, and no batching, size limits or latency behaviour is 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?

Three short sentences, front-loaded with the extraction scope, then cost, then the user-facing rationale. Every sentence carries information, though the final clause ('without retyping') is marketing framing rather than operational guidance.

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 enumerating the returned fields, which is the most important completeness requirement here. It still leaves two things unresolved: how this differs from the sibling extractors, and whether the input is raw text or a PDF, a mismatch between description and schema that could cause a failed 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 both parameters are documented structurally and the baseline of 3 applies. The description's field list describes output content rather than parameter meaning, and it adds no detail on the optional currency_hint or on the expected format of the document text, so it does not exceed 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?

Specific verb ('Extract') plus resource (invoice) and an explicit enumeration of the fields returned (supplier, dates, totals, tax, line items, payment terms), so the agent knows exactly what comes back. It does not, however, distinguish itself from near-identical siblings fikra_extract_invoice and fikra_extract_invoice_fields, which an agent would have no basis to choose between.

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, and never names an alternative. With three overlapping invoice-extraction siblings in the catalog, the absence of any routing rule is a real gap; the only hint is the implicit 'PDF or pasted invoice' input framing.

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 that this is not read-only and not idempotent, so the agent knows a mutating, chargeable call is involved. The description adds the one thing annotations cannot carry: a fixed price of $0.15 per call, which matters for a billing-sensitive flow. It omits practical behaviour such as input size limits or what happens on an unparseable receipt, keeping it below 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?

Three short fragments, front-loaded with the highest-value information (what gets extracted). The final fragment is a dangling noun phrase with no verb, which is slightly wasteful, but nothing is padded or repetitive.

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 enumerating the extracted fields, and it discloses the per-call cost. For a single-parameter text-in tool that is nearly sufficient; only edge-case behaviour (multi-receipt input, unparseable documents) is unstated.

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% on the single 'document' parameter, so the schema already explains that it takes document text. The description adds nothing about the parameter — the merchant/date/total list describes the return payload, not the input. Baseline 3 applies where the schema does 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?

A specific verb plus resource plus explicit output fields: 'Extract merchant, date, total, tax and items from a receipt.' An agent knows exactly what it gets back. It does not, however, distinguish itself from near-neighbours such as fikra_get_receipt or fikra_extract_invoice_fields, so the sibling differentiation is left 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 trailing fragment 'Logging expenses from receipts without manual entry' implies the use case (expense capture) but reads as a marketing line rather than guidance. No when-not conditions and no named alternative such as fikra_get_receipt or fikra_reconcile_invoice_receipt, so the routing decision 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the billing model ('paid per call (x402 or API key)'), but leaves it ambiguous whether the quote call itself is charged, whether auth is required for quoting, and how long a quote is valid.

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 tightly written sentences with the purpose front-loaded and no filler. The brevity is appropriate to a quote tool, though it leaves no room for the parameter clarification the low schema coverage requires.

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?

A 5-parameter tool with 0 required params, 20% schema coverage, no annotations, and no output schema. The description does not explain which parameters are needed for chat vs embeddings, nor what the returned price looks like (units, expiry), leaving the agent under-equipped 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 only 20% across 5 parameters, so the description needs to compensate and does not. It never explains model, messages, max_tokens, or input, and only obliquely hints at the 'type' enum via 'chat or embeddings'.

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: it retrieves the exact x402 USDC price for a planned chat or embeddings call. It is clearly distinguishable from fikra_chat (which performs the call) and fikra_list_models, though it never names those siblings 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?

'Before paying' implies the usage timing — quote first, then make the paid call — but no explicit when-not conditions or alternatives (e.g., that fikra_chat consumes the quote) are given. Usage must be inferred from the phrase rather than read.

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

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

The description adds genuinely useful information not in the annotations: a fixed $0.20 per-call price, which matters for a non-idempotent tool where repeat calls cost money. However, it does not explain why readOnlyHint=false and idempotentHint=false apply to what reads like a verification operation, nor does it describe the verdict format or what happens on partial matches.

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 core action and the cost disclosure early. The final fragment ("Confirming an invoice was paid in full and on time.") is slightly awkward but still earns its place as use-case framing.

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, no parameter descriptions, and annotations that only declare safety flags, the description should say what the result looks like (match/no-match, discrepancy list) and what input forms are accepted. For a two-required-parameter tool with 0% schema coverage, these omissions leave the agent guessing.

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

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

Schema coverage is 0% and both parameters are bare strings with no descriptions. The description does not clarify whether invoice/receipt should be file paths, IDs, raw text, or structured objects — the single most important ambiguity for calling this tool correctly.

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: check whether a payment receipt matches an invoice. That is clearly distinct from siblings like fikra_extract_invoice or fikra_compare_invoices, but the description never names those alternatives to reinforce the distinction.

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?

"Confirming an invoice was paid in full and on time" implies the use case (payment verification) but gives no explicit when-to-use versus when-not, and no routing to siblings such as fikra_process_receipt or fikra_compare_invoices. Usage is inferable rather than 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?

The price disclosure ($0.10 per call) is real behavioral context not present in the annotations, and it matters because idempotentHint=false and readOnlyHint=false mean repeated calls are billable. It stops short of explaining latency, failure modes, or that the result is a paid one-shot analysis.

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, purpose front-loaded, pricing before the usage hint. Nothing is padded, though the PR framing sentence is the weakest of the three in information density.

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 review tool with no output schema and no annotated safety profile beyond false flags, it never says what a review returns — a list of issues, a verdict, a score, or prose — nor whether outputs are bounded by input length. The agent can call it but cannot anticipate or plan around 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?

Schema description coverage is 0% for all three parameters, and the description does not compensate at all — it says nothing about what 'context' should contain or whether 'language' is an identifier, a file extension, or free text. Only the required 'code' parameter is self-evident from its name.

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 plus scope: review a code snippet for bugs, risks and clarity. That distinguishes it from data-extraction siblings like fikra_explain_json or fikra_debug_sql, 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?

"A second pass before opening a pull request" implies a usage context but not a decision rule: no exclusions, no alternatives, and no guidance on when a full review is overkill versus fikra_debug_sql or fikra_generate_unit_tests.

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?

Since there are no annotations, the description is responsible for behavioral details. Stating the action is 'Free' is a behavioral trait, but it fails to disclose crucial operational behaviors such as immediate access invalidation, required permissions for revocation, or potential failure modes.

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 perfectly concise. It delivers the essential purpose and a key operational detail ('Free') in two short, efficient sentences without any unnecessary fluff.

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

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

While it is functionally clear how to call the tool once the `key_id` is known, the overall definition is weak. A revocation tool requires more contextual information regarding potential security implications and necessary authorization levels to be truly complete.

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

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

The input schema is simple, and the description adds zero semantic value to the required `key_id`. It gives no indication of the format or nature of the ID (e.g., UUID, alphanumeric token), which is critical for a mutation tool.

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

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

The description clearly states the action (revoke) and the resource (API key). While it doesn't name the specific sibling it is replacing (like a list sibling), it successfully identifies the unique purpose of 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?

The description provides no guidance on when this tool should be used relative to others. There is no context provided about requiring a prior listing (e.g., using `fikra_list_api_keys`) or any prerequisites for the revocation.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses pricing ($0.2 per call) and a compliance constraint, but omits permissions, rate limits, data handling, and error 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 core action and output format, followed by a compliance note and price. No wasted wording.

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 no output schema, and 'structured JSON' is not further described, so an agent does not know the response shape. The description covers the basic purpose and a compliance constraint but leaves behavioral and output details 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 coverage is 100%, so the two parameters are fully documented in the schema. The description adds no syntax or format details beyond restating that a CV is screened against a job description.

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 (screen) and resources (CV against job description) plus the output format (structured JSON). It does not explicitly differentiate itself from sibling tools, but the purpose is clear enough for an agent to select 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?

Provides a compliance constraint ('No protected-class inferences') but no guidance on when to use this tool versus alternatives such as fikra_chat or fikra_quote. Usage is only implied by the verb 'screen'.

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

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

No annotations are provided, so the description carries the full burden and does not meet it. It says nothing about whether caps are enforced or merely advisory, whether omitted caps are left untouched or cleared, whether 0 means unlimited, or what permissions are required to mutate a key's budget. "Free" is the only behavioral fact 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?

Two clipped sentences, zero filler, with the action and scope front-loaded before the cost note. Nothing could be removed without losing content.

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 an unannotated mutation tool with no output schema and zero parameter documentation in the schema, so the description has to do the heavy lifting and does not. An agent cannot confirm side effects, idempotency, or the meaning of key_id before writing.

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

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

Schema description coverage is 0%, so all three parameters are bare names. The description clarifies the USD unit and daily/monthly nature of the two cap fields, but not what key_id refers to or where to obtain it, and it is ambiguous whether both caps may be set simultaneously despite the "or" phrasing.

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 ("Set ... USD caps on a key") plus the two dimensions of the cap (daily or monthly), so an agent can tell this is a budget-configuration mutation. It does not name or contrast with adjacent siblings like fikra_list_api_keys (where key_id comes from) or fikra_get_usage (which reports spend against the cap).

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?

"Daily or monthly" hints at the configuration choice and "Free" signals no cost, but there is no guidance on when to use this versus fikra_get_usage/fikra_list_api_keys, no prerequisites (ownership/admin rights on the key), and no statement about overwriting an existing cap.

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 destructiveHint=false, openWorldHint=false and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: a fixed $0.10 per-call charge, which matters because the call is non-idempotent and retries cost money. It says nothing about transcript length limits, language handling, or why readOnlyHint is false (presumably usage/billing writes).

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 core action, zero structural waste. 'A quick read of a long recording' is the weakest line but still carries a use-case signal rather than pure 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?

Context is simple: one required string parameter, no output schema, no nested objects, flat annotations. The description covers action, cost, and intent, which is enough for an agent to call it correctly; the missing return-format detail is excused by the absence of an output schema only insofar as the shape is predictable ('key points').

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?

One parameter with 0% schema description coverage, so the description must carry the load. 'Summarise a transcript' implies the input is raw transcript text, but it adds no constraints on format, length, timestamps, or language, so the agent still has to guess what a valid transcript looks like.

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: 'Summarise a transcript into key points', which separates it from siblings like fikra_summarise_contract and fikra_summarise_research by input type. Minor friction: the tool is named 'summarise_audio' but the description only ever refers to a transcript, so an agent may briefly wonder whether it accepts audio files.

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?

'A quick read of a long recording' implies the use case (long input, want a condensed read) but names no alternatives and gives no when-not conditions. With fikra_generate_meeting_minutes and fikra_extract_meeting_actions as nearby siblings, an agent gets no routing guidance between summarising and structured extraction.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses cost ($0.5 per call) and a legal disclaimer, but omits contract text handling, storage, privacy, output format, and failure 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?

Three short sentences, each earning its place: purpose first, then legal disclaimer, then pricing. No filler or repetition.

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

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

For a simple one-parameter tool with no output schema, the description sufficiently states the summary dimensions and cost. It could be stronger by specifying output format or length, but it is broadly complete for invocation.

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

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

Schema description coverage is 100% for the single required parameter, so the schema already defines 'document' as contract text. The description adds no parameter syntax, length limits, or format guidance beyond that 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 and resource: summarize a contract, and specifies the exact output dimensions (parties, dates, obligations, risks). This clearly distinguishes it from sibling tools like invoice extraction and CV screening without requiring schema inspection.

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 task implies when to use it—when a contract needs summarization—but gives no explicit alternatives, exclusions, or conditions. There is no guidance on when to use fikra_quote, fikra_chat, or other siblings instead.

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